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.

POST /v1/ingest accepts batches of evaluation results produced by your gates and updates each agent’s rolling reputation window. The endpoint is designed for high-throughput, asynchronous delivery — Pecta queues each event for background processing and updates reputation scores before returning.
This endpoint is called automatically by PectaTelemetry in @pecta/core and by pecta-proxy. Most customers never need to call it directly. Use it when you are building a custom integration or shipping telemetry from a platform that cannot run the Node.js SDK.

​
Endpoint

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

​
Authentication

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

​
Optional HMAC signature

If you have HMAC signing enabled, include the X-Pecta-Signature header with the HMAC-SHA256 digest of the raw request body: 
X-Pecta-Signature: sha256=<hex-digest>
The digest is computed as HMAC-SHA256(rawBody, sk_live_key). When the header is present, Pecta verifies it before parsing the body. Omitting the header skips signature verification. See Authentication for details.

​
Request body

​
events
array
required
Array of evaluation events. Must contain between 1 and 100 items.

​
Response fields

The server responds with 202 Accepted once events are queued. Persistence is handled asynchronously in the background.
​
accepted
number
Number of events accepted from the batch.
​
reputation_updates
array
Updated reputation summary for each unique agent in the batch.

​
Example request

curl --request POST \
  --url https://api.pecta.ai/v1/ingest \
  --header "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  --header "Content-Type: application/json" \
  --data '{
    "events": [
      {
        "agent_id": "bid-agent-prod",
        "tool": "submit_bid",
        "passed": true,
        "gates": [
          { "name": "impid",      "passed": true,  "latency_ms": 1 },
          { "name": "bid_sanity", "passed": true,  "latency_ms": 2 },
          { "name": "adomain",    "passed": true,  "latency_ms": 1 }
        ],
        "total_latency_ms": 4,
        "timestamp": "2026-05-07T14:22:10.000Z"
      },
      {
        "agent_id": "bid-agent-prod",
        "tool": "submit_bid",
        "passed": false,
        "gates": [
          { "name": "impid",      "passed": true,  "latency_ms": 1 },
          { "name": "bid_sanity", "passed": false, "latency_ms": 2,
            "reason": "bid price exceeds floor by more than 50x" },
          { "name": "adomain",    "passed": true,  "latency_ms": 1 }
        ],
        "total_latency_ms": 4,
        "timestamp": "2026-05-07T14:22:11.000Z"
      }
    ]
  }'

​
Example response

{
  "accepted": 2,
  "reputation_updates": [
    {
      "agent_id": "bid-agent-prod",
      "score": 731,
      "status": "mature"
    }
  ]
}