> ## 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 — batch telemetry ingestion

> Ingest up to 100 evaluation events in one batch. The @pecta/core SDK calls this endpoint automatically — most customers never need to call it directly.

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

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

## 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](/api-reference/authentication) for details.

## Request body

<ParamField body="events" type="array" required>
  Array of evaluation events. Must contain between 1 and 100 items.

  <Expandable title="Event fields">
    <ParamField body="events[].agent_id" type="string" required>
      Identifier for the agent that produced this output. Maximum 200 characters.
    </ParamField>

    <ParamField body="events[].tool" type="string">
      Name of the tool or function called. Maximum 200 characters.
    </ParamField>

    <ParamField body="events[].passed" type="boolean" required>
      Overall gate verdict for this evaluation.
    </ParamField>

    <ParamField body="events[].gates" type="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).
    </ParamField>

    <ParamField body="events[].total_latency_ms" type="number" required>
      Total gate evaluation time in milliseconds. Maximum 60000.
    </ParamField>

    <ParamField body="events[].timestamp" type="string">
      ISO 8601 UTC timestamp for when the evaluation occurred. Defaults to the server's current time when omitted.
    </ParamField>

    <ParamField body="events[].evaluation_id" type="string">
      Optional evaluation ID from a prior `/v1/evaluate` call or your own ID system. Maximum 50 characters.
    </ParamField>
  </Expandable>
</ParamField>

## Response fields

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

<ResponseField name="accepted" type="number">
  Number of events accepted from the batch.
</ResponseField>

<ResponseField name="reputation_updates" type="array">
  Updated reputation summary for each unique agent in the batch.

  <Expandable title="Reputation update fields">
    <ResponseField name="reputation_updates[].agent_id" type="string">
      The agent identifier.
    </ResponseField>

    <ResponseField name="reputation_updates[].score" type="number">
      Updated 0–1000 reputation score.
    </ResponseField>

    <ResponseField name="reputation_updates[].status" type="string">
      Lifecycle stage: `"new"`, `"calibrating"`, `"active"`, or `"mature"`.
    </ResponseField>
  </Expandable>
</ResponseField>

## Example request

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

```json theme={null}
{
  "accepted": 2,
  "reputation_updates": [
    {
      "agent_id": "bid-agent-prod",
      "score": 731,
      "status": "mature"
    }
  ]
}
```