/Documentation/DocumentationEverything you need to integrate Incept question generation into your application
Get up and running in 3 simple steps. You'll be generating questions in under 5 minutes.
Go to the API Keys page and click "Create New Key". Give it a name and select which generators you want access to.
Important: Copy your API key immediately after creation. For security, the full key is only shown once. Store it securely - treat it like a password.
Use the following cURL command to generate your first question. Replace YOUR_API_KEY with the key you just created.
curl -X POST "https://api.inceptapi.com/v1/generate" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"generator_name": "incept-agentic-math2",
"instructions": "Algebra",
"grade": "5",
"subject": "math",
"quantity": 1,
"difficulty": "medium"
}'The API returns a JSON response with your generated questions:
{
"success": true,
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"data": {
"questions": [
{
"id": "q-0",
"type": "mcq",
"question": "What is 2/5 + 1/5?",
"answer": "A",
"options": [
{ "key": "A", "text": "3/5" },
{ "key": "B", "text": "3/10" },
{ "key": "C", "text": "2/10" },
{ "key": "D", "text": "1/5" }
],
"explanation": "When adding fractions with the same denominator, add the numerators: 2 + 1 = 3. The answer is 3/5.",
"difficulty": "medium"
}
],
"meta": {
"generator_name": "incept-agentic-math2",
"generator_display_name": "Incept Agentic Math 2",
"latency_ms": 2345,
"total_questions": 1,
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}
}All API requests require authentication using a Bearer token. Include your API key in theAuthorization header of every request.
Authorization: Bearer YOUR_API_KEYconst response = await fetch("https://api.inceptapi.com/v1/generate", {
method: "POST",
headers: {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
},
body: JSON.stringify({
generator_name: "incept-agentic-math2",
instructions: "Algebra",
grade: "5",
subject: "math",
quantity: 1,
difficulty: "medium"
})
});
const data = await response.json();
console.log(data.data.questions);/v1/generateTwo ways to call this endpoint:
instructions — provide a natural-language prompt. The API auto-detects grade, subject, type, and curriculum alignment.skills — provide curriculum alignment directly. You must also include grade, subject, and type.| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
generator_name | string | Yes | — | Generator ID (use GET /v1/generate to list) |
instructions | string | Conditional | — | Natural-language prompt (min 3 chars). Required unless skills is provided. |
skills | object | Conditional | Auto-fetched | Curriculum alignment. Required unless instructions is provided. See below. |
grade | string | Conditional | "5" | Grade level: "K", "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "AP". Required when using skills without instructions. |
subject | string | Conditional | "math" | "math", "ela", "social studies", "social science", "apush", "apwh", "apeuro". Required when using skills without instructions. |
type | string | Conditional | "mcq" | "mcq", "msq", "fill-in", "match", "article", "saq", "leq", "dbq", or "mcq_set". Required when using skills without instructions. |
difficulty | string | No | "medium" | "easy", "medium", or "hard" |
locale | string | No | "en-US" | "en-US", "en-AE", or "ar-AE" |
quantity | number | No | 1 | Number of questions (1–50) |
Provide curriculum alignment directly. Only substandard_id is required. The ID is matched first — if it matches a known standard, the other fields are ignored. If it doesn't match, lesson_title and substandard_description are used for semantic matching.
| Field | Type | Description |
|---|---|---|
substandard_id | string | Required Standard ID (e.g., CCSS.MATH.CONTENT.4.NF.B.3a) |
lesson_title | string | Lesson title (used as fallback for semantic matching) |
substandard_description | string | Standard description (used as fallback for semantic matching) |
{
"skills": {
"substandard_id": "CCSS.MATH.CONTENT.4.NF.B.3a"
}
}/v1/generateReturns a list of all enabled generators your API key has access to.
curl "https://api.inceptapi.com/v1/generate" \
-H "Authorization: Bearer YOUR_API_KEY"/v1/qti/buildUse this endpoint when you already have question JSON plus curriculum packaging metadata and want QTI XML back without uploading.
{
"items": [
{
"question": {
"id": "q1",
"type": "mcq",
"question": "What is 3 x 4?",
"answer": "A",
"options": [
{ "key": "A", "text": "12" },
{ "key": "B", "text": "7" },
{ "key": "C", "text": "34" },
{ "key": "D", "text": "1" }
]
},
"packaging": {
"curriculum": "Common Core Standard",
"course": "3rd Grade",
"standard": "CCSS.MATH.CONTENT.3.OA.A.1"
}
}
]
}{
"success": true,
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"data": {
"item_count": 1,
"items": [
{
"question_id": "q1",
"item_id": "q1",
"xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><qti-assessment-item ... />"
}
]
}
}/v1/qti/publishAccepts the same request shape as /v1/qti/build, then uploads the transformed items and returns the TimeBack job result.
{
"success": true,
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"data": {
"job_id": "job_123",
"status": "COMPLETED",
"item_count": 1,
"content_browser_url": "https://app.timeback.com/...",
"item_outcomes": []
}
}QTI publish failures may return both an error object and a partial data payload so you can correlate SDK diagnostics with the attempted upload.
3 generators currently available. Use GET /v1/generate to list available generators programmatically.
Generator ID
incept-agentic-math
Grade & subject support
Generator ID
incept-agentic-math2
Grade & subject support
Generator ID
incept-agentic-2-ela
Grade & subject support
All errors follow a consistent format with a machine-readable code and human-readable message.
{
"success": false,
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid or missing API key"
}
}| Code | HTTP Status | Description |
|---|---|---|
INVALID_REQUEST | 400 | Request body is invalid or missing required fields |
UNAUTHORIZED | 401 | API key is missing or invalid |
FORBIDDEN | 403 | API key doesn't have permission for this generator |
RATE_LIMITED | 429 | Too many requests. Wait and try again |
QUOTA_EXCEEDED | 429 | Daily or monthly quota exceeded |
GENERATOR_NOT_FOUND | 404 | The specified generator doesn't exist |
GENERATOR_UNSUPPORTED_COMBINATION | 422 | Generator doesn't support the requested grade + subject combination |
GENERATOR_ERROR | 500 | Generator failed to process the request |
GENERATOR_TIMEOUT | 504 | Generator took too long to respond |
GENERATOR_UNAVAILABLE | 503 | Generator is temporarily unavailable |
INTERNAL_ERROR | 500 | Unexpected server error |
QTI_BUILD_FAILED | 500 | QTI XML build failed |
QTI_PUBLISH_FAILED | 500 | QTI publish failed before a job result was available |
QTI_JOB_FAILED | 422 | TimeBack accepted the upload job but one or more items failed during processing |
API requests are rate limited to ensure fair usage. Rate limit information is included in response headers.
| Header | Description |
|---|---|
X-RateLimit-Limit | Maximum requests per minute |
X-RateLimit-Remaining | Remaining requests in current window |
X-RateLimit-Reset | Unix timestamp when the limit resets |
Retry-After | Seconds to wait (only on 429 responses) |
If you receive a 429 response, wait for the number of seconds specified in theRetry-After header before making another request. Implement exponential backoff for best results.
Get started quickly.