POST /v1/ingest — batch telemetry ingestion

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

array

required

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

Show Event fields

string

required

Identifier for the agent that produced this output. Maximum 200 characters.

string

Name of the tool or function called. Maximum 200 characters.

boolean

required

Overall gate verdict for this evaluation.

array

required

Per-gate results. Maximum 50 gates per event. Each element must include name (string, max 200), passed (boolean), latency_ms (number), and optionally reason (string, max 500) and skipped (boolean).

number

required

Total gate evaluation time in milliseconds. Maximum 60000.

string

ISO 8601 UTC timestamp for when the evaluation occurred. Defaults to the server’s current time when omitted.

string

Optional evaluation ID from a prior /v1/evaluate call or your own ID system. Maximum 50 characters.

Response fields

The server responds with 202 Accepted once events are queued. Persistence is handled asynchronously in the background.

number

Number of events accepted from the batch.

array

Updated reputation summary for each unique agent in the batch.

Show Reputation update fields

string

The agent identifier.

number

Updated 0–1000 reputation score.

string

Lifecycle stage: "new", "calibrating", "active", or "mature".

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"
    }
  ]
}

Overview

Endpoints

POST /v1/ingest — batch telemetry ingestion

Endpoint

Authentication

Optional HMAC signature

Request body

Response fields

Example request

Example response

​Endpoint

​Authentication

​Optional HMAC signature

​Request body

​Response fields

​Example request

​Example response

Endpoint

Authentication

Optional HMAC signature

Request body

Response fields

Example request

Example response