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

# Evaluate agent output via the Pecta REST API

> Send agent output to POST /v1/evaluate from any language and get a gate verdict, evaluation ID, and live reputation score back in a single HTTP response.

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.

<Steps>
  <Step title="Get an API key">
    Sign in at [pecta.ai](https://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:

    ```bash theme={null}
    export PECTA_API_KEY=pk_live_xxx
    ```
  </Step>

  <Step title="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.

    <CodeGroup>
      ```bash curl theme={null}
      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
        }'
      ```

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

      ```typescript node.js theme={null}
      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);
      ```
    </CodeGroup>
  </Step>

  <Step title="Read the response">
    A successful evaluation returns HTTP 200 with the verdict, per-gate detail, total latency, and the agent's current reputation score.

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

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

  <Step title="Handle errors">
    API errors return a non-2xx status with a structured body:

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

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

<Warning>
  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.
</Warning>