Skip to main content
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

MethodPathDescription
POST/v1/evaluateRun cloud gate evaluation on an agent output
POST/v1/ingestIngest a batch of telemetry events from SDK or proxy
GET/v1/eventsList paginated evaluation events for your org
GET/v1/reputation/:agentIdFetch the current reputation score for an agent
GET/v1/agentsList all agents registered to your org
POST/v1/agentsRegister an agent explicitly
GET/healthHealth 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 statusCodeMeaning
400validation_errorRequest body failed schema validation
400bad_jsonRequest body is not valid JSON
401auth_missingNo Authorization header present
401auth_invalidKey not found
401auth_revokedKey has been revoked
401hmac_invalidHMAC signature does not match
429rate_limitedRate limit exceeded — see below

​
Rate limiting

Pecta applies per-org, per-minute rate limits on a rolling 60-second window.
EndpointLimit
POST /v1/ingest500 requests / minute
All other /v1/* routes200 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
}