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.
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
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>
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.
All error responses share the same shape:
{
"error": "human-readable message",
"code": "machine_readable_code",
"status": 401
}
| 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 |
429 with a Retry-After header indicating how many seconds to wait before retrying.
{
"error": "rate limit exceeded",
"code": "rate_limited",
"status": 429
}