Pecta REST API: endpoints, auth, and errors

The Pecta REST API lets you run cloud-side gate evaluations, ingest batched telemetry, query evaluation events, and fetch agent reputation scores over standard HTTP. All endpoints live under https://api.pecta.ai and require an Authorization: Bearer <key> header on every /v1/* route.

Base URL

https://api.pecta.ai

Endpoints

Method	Path	Description
`POST`	`/v1/evaluate`	Run cloud gate evaluation on an agent output
`POST`	`/v1/ingest`	Ingest a batch of telemetry events from SDK or proxy
`GET`	`/v1/events`	List paginated evaluation events for your org
`GET`	`/v1/reputation/:agentId`	Fetch the current reputation score for an agent
`GET`	`/v1/agents`	List all agents registered to your org
`POST`	`/v1/agents`	Register an agent explicitly
`GET`	`/health`	Health check — no auth required

Authentication

Every /v1/* request must include your API key in the Authorization header:

Authorization: Bearer pk_live_<your-key>

Pecta issues two key types — pk_live_ (publishable) and sk_live_ (secret). Use pk_live_ for reads and client-visible configs; use sk_live_ for server-to-server calls. See the Authentication page for full details.

Error format

All error responses share the same shape:

{
  "error": "human-readable message",
  "code": "machine_readable_code",
  "status": 401
}

Common codes:

HTTP status	Code	Meaning
`400`	`validation_error`	Request body failed schema validation
`400`	`bad_json`	Request body is not valid JSON
`401`	`auth_missing`	No `Authorization` header present
`401`	`auth_invalid`	Key not found
`401`	`auth_revoked`	Key has been revoked
`401`	`hmac_invalid`	HMAC signature does not match
`429`	`rate_limited`	Rate limit exceeded — see below

Rate limiting

Pecta applies per-org, per-minute rate limits on a rolling 60-second window.

Endpoint	Limit
`POST /v1/ingest`	500 requests / minute
All other `/v1/*` routes	200 requests / minute

When you exceed the limit the API returns 429 with a Retry-After header indicating how many seconds to wait before retrying.

{
  "error": "rate limit exceeded",
  "code": "rate_limited",
  "status": 429
}

​Base URL

​Endpoints

​Authentication

​Error format

​Rate limiting

Base URL

Endpoints

Authentication

Error format

Rate limiting