Getting Started

Base URL

https://eval-api.magicblocks.ai

Authentication

Two authentication methods are used depending on the endpoint:

Webhook

HMAC-SHA256 Signature

For POST /api/eval. Include signature in the X-Eval-Signature header. Computed as HMAC-SHA256(body, workspace_secret).

API Key

Bearer Token

For all other endpoints. Include in the Authorization: Bearer <api_key> header.

Integration Flow

Send Webhook→

Receive 202→

Poll Status→

Get Result

1. POST the conversation payload to /api/eval. Returns 202 Accepted with an evalId.

2. Poll GET /api/eval/:sessionId/status every 5 seconds. The response includes a Retry-After header.

3. When status is complete, fetch the full result from GET /api/eval/:sessionId/result.

4. Status lifecycle: pending → processing → complete | failed

Endpoint Reference

Method	Path	Purpose	Auth
POST	/api/eval	Submit conversation for evaluation	HMAC
GET	/api/eval/:sessionId/status	Poll evaluation status	API Key
GET	/api/eval/:sessionId/result	Get full evaluation result	API Key
GET	/api/evals	List evaluations (paginated)	API Key
DELETE	/api/eval/:evalId	Delete single evaluation	API Key
POST	/api/evals/bulk-delete	Delete multiple evaluations (up to 100)	API Key
GET	/api/config/:agentId	Get agent evaluation config	API Key
PUT	/api/config/:agentId	Update agent evaluation config	API Key
GET	/api/prompt	Get current system prompt	API Key
PUT	/api/prompt	Update system prompt (new version)	API Key
GET	/api/prompt/versions	List prompt version history	API Key
POST	/api/prompt/rollback	Rollback to a specific prompt version	API Key
POST	/api/simulate	Run test eval synchronously (simulator)	API Key
GET	/api/health	Health check and system stats	None

Webhook Payload Schema

Only three fields are required. All others degrade gracefully when missing.

Required Fields

workspaceId — workspace identifier
session.id — unique session ID
session.messages[] — conversation transcript

Optional Fields

session.channel, durationMs, goals, keyFacts, summary
contact — name, emails, phones
agent — id, name, purpose, industry
evalConfig — inline rules, watchlist, topics
messageMetadata — per-message sentiment/flags

curl -X POST https://eval-api.magicblocks.ai/api/eval \
  -H "Content-Type: application/json" \
  -H "X-Eval-Signature: sha256=<hmac_signature>" \
  -d '{
    "workspaceId": "ws_demo",
    "session": {
      "id": "sess_123",
      "messages": [
        { "id": "m1", "role": "agent", "content": "Hello!" },
        { "id": "m2", "role": "lead", "content": "Hi there" }
      ]
    }
  }'

Polling Status Responses

pending

{ "status": "pending", "sessionId": "sess_123", "queuedAt": "2026-04-09T14:00:00Z", "retryAfter": 5 }

processing

{ "status": "processing", "sessionId": "sess_123", "startedAt": "2026-04-09T14:00:05Z", "retryAfter": 5 }

complete

{ "status": "complete", "sessionId": "sess_123", "evalId": "eval_abc123",
  "completedAt": "2026-04-09T14:00:20Z",
  "resultUrl": "/api/eval/sess_123/result",
  "summary": { "npsScore": 8, "flagged": false, "complianceRating": "compliant" } }

failed

{ "status": "failed", "sessionId": "sess_123", "error": "AI model timeout", "retryable": true }

Error Codes

Code	HTTP	Description
INVALID_PAYLOAD	400	Payload failed validation (details in response)
MISSING_REQUIRED_FIELD	400	A required field (messages, sessionId, workspaceId) is missing
DUPLICATE_SESSION	409	Session already queued or evaluated
EVAL_NOT_FOUND	404	No eval exists for this session or eval ID
UNAUTHORIZED	401	Invalid or missing API key / HMAC signature
RATE_LIMITED	429	Too many requests (check Retry-After header)
INTERNAL_ERROR	500	Unexpected server error

Error Response Format

{
  "error": {
    "code": "EVAL_NOT_FOUND",
    "message": "No evaluation found for session sess_abc123",
    "requestId": "req_a1b2c3d4e5f6"
  }
}