Skip to main content

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.

Every request to a /v1/* endpoint must carry a valid API key. Pecta issues two key types with different trust levels, and the @pecta/core SDK optionally signs telemetry payloads with an HMAC signature for additional integrity guarantees.

​
Key types

Pecta API keys follow the format pk_live_<32 chars> or sk_live_<32 chars>. The prefix tells you what the key is allowed to do.
PrefixTypeSafe to expose?Use for
pk_live_PublishableYes — config files, .env on clientReads, /v1/evaluate, telemetry ingest, MCP proxy
sk_live_SecretNo — server environment onlyAdmin operations, HMAC signing
Keys are shown only once at creation time and stored as SHA-256 hashes in Pecta’s database.
Never embed a sk_live_ key in client-side code, browser bundles, or any repository that is or could become public. If a secret key is exposed, revoke it immediately from the dashboard.

​
Authorization header

Pass your key as a Bearer token on every /v1/* request: 
Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Full example with curl: 
curl https://api.pecta.ai/v1/agents \
  --header "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

​
HMAC signing for telemetry

When the @pecta/core SDK is configured with a secretKey, it signs every ingest payload with HMAC-SHA256 and includes the signature in the X-Pecta-Signature request header. This lets Pecta verify the payload was not tampered with in transit. The header format is: 
X-Pecta-Signature: sha256=<hex-digest>
The digest is computed as: 
HMAC-SHA256(raw-request-body, sk_live_key)
Pecta computes the expected digest server-side and compares it using a constant-time comparison (timingSafeEqual) to prevent timing attacks. If the header is present but the digest does not match, the request is rejected: 
{
  "error": "HMAC signature does not match",
  "code": "hmac_invalid",
  "status": 401
}
The X-Pecta-Signature header is optional. If you omit it, ingest proceeds without signature verification. Enable HMAC in the SDK with: 
const telemetry = new PectaTelemetry({
  publishableKey: 'pk_live_...',
  secretKey: 'sk_live_...',
  hmac: true,
});
Enable HMAC signing whenever you use @pecta/core in an RTB or otherwise latency-critical environment where payload integrity matters.

​
401 response

When authentication fails, the API returns 401 with a machine-readable code field: 
{
  "error": "missing or malformed Authorization header",
  "code": "auth_missing",
  "status": 401
}
CodeCause
auth_missingNo Authorization header, or header is malformed
auth_formatKey does not match the pk_live_ / sk_live_ format
auth_invalidKey not found in the database
auth_revokedKey exists but has been revoked
hmac_no_secretHMAC header was sent but no secret key is on file
hmac_invalidHMAC digest does not match the request body