Frequently asked questions

How do I authenticate?

Send your key in the Authorization header using either Token token=sk_intu_api_… or Bearer sk_intu_api_…. Both work identically. See Authentication.

What is user_id and do I need it?

user_id is your identifier for the end-student a request is for (any stable string — a UUID, your DB id, etc.). Pass it at the root of the request body on POST requests. We use it to attribute usage and billing per student and to power the student progress digest. It is not an Intu AI id.

Should I poll or use webhooks?

Prefer webhooks — configure a URL per event type and we POST the result the moment generation finishes. Polling (GET the resource until status is terminal) is the fallback for consumers who haven’t wired webhooks yet. Both are always available. See Webhooks.

How do I verify a webhook came from Intu AI?

Each delivery is signed. Compute HMAC-SHA256(secret, "{timestamp}.{body}") and compare it (constant-time) to the X-IntuAI-Signature header, using the X-IntuAI-Timestamp header as the timestamp. Your signing secret is shown in the admin console. See Webhooks.

What are the rate limits?

100 requests/minute per token. A 429 includes a Retry-After header. See Errors.

Are requests idempotent / retried?

Failed webhook deliveries are retried automatically with exponential backoff (up to 3 attempts). API requests themselves are not deduplicated — if a 202 create times out on your side, poll the resource before retrying so you don’t generate twice.

What file formats are accepted?

Marking and exam-marking accept PDF uploads (sniffed by content, not by extension). Explain-back answers accept common audio formats (audio/*, webm/ogg) which we transcribe server-side.

How do I mark a generated exam?

Generate a paper with the Exams API, then submit the student’s completed work to POST /mark/submissions using the assessment_id returned with the paper. The exam and Mark apps share the same assessment.

Which curricula and subjects are available?

Subjects span the Australian state curricula (NSW HSC senior subjects, plus Years 7–10 Maths & Science across NSW, VIC, QLD, SA, TAS and WA) and the IB Diploma Programme — Biology, Chemistry, Physics, Mathematics: Analysis & Approaches, Economics, English A: Language & Literature and History, each at Higher and Standard Level (location: "IB"). The exact set you can use is your subscription’s granted subjects — call List subjects to see them. Access is governed by your subscription, not by the end-student’s location.

Which app does each endpoint need?

Chats need ask, quizzes quiz, marking mark, exams exams_api, study study, NAPLAN naplan_api. A request to a disabled app returns 403 APP_NOT_ENABLED. See Introduction.