Going live

​

1. Keys per environment

• One key per environment and per system. Separate keys for staging and production, and for each system that calls the API (for example the ERP backend and a nightly sync job). You can then revoke one without stopping the others, and tell their traffic apart.
• Give each key only the scopes it needs. New keys get evaluation:read and evaluation:write.

• Set an expiry for keys used in pilots or by contractors.
• Check each key with GET /me. It needs no scope and returns who the key is and what it can do:

curl https://api.evalezy.com/v1/me -H "X-API-Key: $EVALEZY_API_KEY"

{
  "key_id": "5c1e8a47-2f3b-4d9e-a6c0-71b8e2d4f915",
  "name": "ERP production",
  "institute_id": "9a7d3c21-64e8-4b0f-8c52-3e1f0a9b6d47",
  "institute_name": "Green Valley Public School",
  "scopes": ["evaluation:read", "evaluation:write"],
  "rate_tier": "standard",
  "daily_copy_quota": 2000,
  "daily_copy_cap": null,
  "quota_used_today": 0,
  "quota_resets_at": "2026-10-03T00:00:00Z"
}

​

2. Store keys as secrets

• Server-to-server only. Never put a key in a web page, a mobile app or any code that runs on a user’s device. Your app calls your backend; your backend calls Evalezy.
• Keep it in a secret manager or an environment variable injected at deploy time, never in source control.
• Never log the full key. Log the first 16 characters if you need to tell keys apart.
• Rotate without downtime. Create the new key, deploy it, confirm traffic with GET /me, then revoke the old key. Revocation takes effect within about a minute.
• Revoke at once if a key may have leaked, then create a new one.

​

3. Retries with Idempotency-Key

• Derive the key from your own IDs, for example sub-{exam_id}-{student_id}-{upload_id}, so a retry after a crash reuses it. Any printable ASCII string up to 255 characters works.
• Same key, same request: you get the stored response again, with the header Idempotent-Replayed: true.
• Same key, different request: 422 idempotency_key_reused. This is a bug in how you build keys.
• Same key while the first request is still running: 409 request_in_progress. Wait a moment and retry with the same key.
• Keys are kept for 48 hours, per institute, so a retry from a second key of the same institute replays too.

​

4. Error handling

{
  "error": {
    "code": "validation_failed",
    "message": "max_marks must be a multiple of 0.5.",
    "request_id": "req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f",
    "details": {
      "errors": [
        { "field": "questions[3].max_marks", "code": "invalid_step", "message": "max_marks must be a multiple of 0.5." }
      ]
    }
  }
}

​

Text you send

• All text is plain text, never rendered as HTML. Send text, not markup, and render what you read back as text.
• Titles, question and option labels, section names, criterion names and candidate names, roll numbers and classes cannot contain < or >. Such a value returns 422 validation_failed with the field code invalid_characters.
• A NUL character (\u0000) anywhere in a request body returns 422 validation_failed with the field code invalid_characters. Strip it from text copied out of other systems.
• metadata is a JSON object of up to 2 KB.

​

5. Credits

curl https://api.evalezy.com/v1/credits -H "X-API-Key: $EVALEZY_API_KEY"

curl https://api.evalezy.com/v1/credits/quote \
  -H "X-API-Key: $EVALEZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "pages": 3600 }'

• GET /credits returns balance, committed (quoted for copies still in the queue), available (what new submissions can use), the institute’s rate_card and spent_30d.
• POST /credits/quote prices a batch before you submit it. Send exactly one of pages, upload_ids (exact page counts of uploads, up to 100) or typed_answers. The answer has total, available and sufficient.
• A submission that can’t be paid for returns 402 insufficient_credits with required and available in details. Nothing is queued.

​

6. Quotas and rate limits

​

7. The teacher review step

• Decide who reviews. Teachers can review on the institute’s Vacademy dashboard, where API exams are tagged Source: API, or in your own UI through PATCH /submissions/{id}/questions/{question_id} and POST /submissions/{id}/approve.
• Review flagged copies first. needs_review is true when a question failed, the AI’s confidence was low, or a copy had more than 40 pages. Filter with needs_review=true.
• Finalize deliberately. POST /exams/{id}/finalize locks results: overrides and re-evaluation then return 409 submission_finalized. Partially graded and failed copies are skipped unless you send allow_partial.
• Plan for rechecks. POST /submissions/{id}/unfinalize with a reason puts one result back on hold; correct it, then finalize again.

​

8. Know what is not available yet

​

Support