AI, Jobs, and Integrations

Back to API Overview

This page summarizes the cross-endpoint workflows that matter when integrating AI generation, background jobs, gaming, and third-party services.

AI Prompt Human Names (v2)

The AI generation APIs use human-readable prompt names as stable client-facing selectors. Clients should treat these names as documented contract values rather than as arbitrary free-form labels.

Practical guidance:

Current public v2 AI human names:

Human name Function Schemas Sample request Sample response
curriculum-topics-to-activities-v1 Generate localized classroom activity ideas from topics and target learner context. request · response {"topics":["loops","conditions"],"target":{"age":14,"domain":"computer science"}} {"concepts":[{"en_US":"Trace the Loop: Students predict each iteration before running code.","es_ES":"...","fr_FR":"..."}]}
curriculum-standards-to-knowledge-reasoning-performance-v1 Convert curriculum standards and lesson settings into knowledge, reasoning, and performance learning targets. request · response {"curriculumAlignments":[{"urn":"urn:example:standard:cs:loops","parents":["Computer Science"],"label":"Students trace iterative algorithms."}],"depthLevel":"intermediate","scope":"narrow","lessonDuration":"45","lessonComponents":["objectives","instruction","practice"]} {"knowledge":[{"id":"knowledge-loops","title":"Loop State","description":"..."}],"reasoning":[{"id":"reasoning-trace","title":"Trace Execution","description":"..."}],"performance":[{"id":"execution-loop","title":"Implement a Loop","description":"..."}],"conversationSummary":"...","conversationState":{"processedStandards":["urn:example:standard:cs:loops"],"generatedCounts":{"knowledge":1,"reasoning":1,"performance":1}}}
grade-short-freeform-v1 Grade a short freeform student response against a supplied rubric. request · response {"version":1,"submissionMode":"responseText","studentSubmission":{"response":"A loop repeats a block while a condition remains true."},"challengeContext":{"challengeName":"Explain Loops"},"scoring":{"maxScore":4},"rubric":{"criteria":[{"criterionID":"accuracy","label":"Accuracy","maxScore":4,"gradingGuidance":"Award credit for a correct explanation."}]}} {"version":1,"awardedScore":4,"maxScore":4,"feedback":{"summary":"The response correctly explains conditional repetition."},"rubricBreakdown":{"items":[{"criterionID":"accuracy","awardedScore":4,"maxScore":4,"feedback":"Correct and concise."}]}}
knowledge-reasoning-performance-to-lesson-outline-v1 Create a structural lesson outline from knowledge, reasoning, and performance targets. request · response {"knowledge":[{"id":"k1","title":"Loop Condition","description":"..."}],"reasoning":[{"id":"r1","title":"Trace Iterations","description":"..."}],"performance":[{"id":"e1","title":"Write a Loop","description":"..."}],"lessonDuration":"45","lessonOptions":{"gradeLevel":"middle school"}} {"outline":{"title":"Tracing Loops","overview":"...","objectives":["..."],"duration":"45 minutes","sections":[{"sectionType":"instruction","title":"Loop Conditions","purpose":"...","durationMinutes":10,"relatedKnowledgeIds":["k1"],"relatedReasoningIds":[],"relatedExecutionIds":[],"alignedStandardUrns":[],"corpusSearchQueries":["loop condition examples"],"contentGuidance":"..."}],"assessmentStrategy":{"formativeCheckpoints":["..."],"rubricFocusAreas":["..."]}},"conversationSummary":"...","conversationState":{"lessonTitle":"Tracing Loops","lessonDuration":"45","sectionCount":1,"standardsCovered":[],"knowledgeItemsCovered":["k1"],"reasoningItemsCovered":["r1"],"performanceItemsCovered":["e1"]}}
knowledge-reasoning-performance-to-lesson-v1 Create a complete lesson from knowledge, reasoning, and performance targets, using corpus references when available. request · response {"knowledge":[{"id":"k1","title":"Loop Condition","description":"..."}],"reasoning":[{"id":"r1","title":"Trace Iterations","description":"..."}],"performance":[{"id":"e1","title":"Write a Loop","description":"..."}],"rootRealmEIDurn":"urn:ayode:realm-eid:00000000-0000-0000-0000-000000000000","lessonDuration":"45"} {"lesson":{"title":"Tracing Loops","sections":[{"sectionType":"instruction","title":"Loop Conditions","durationMinutes":10,"content":"...","corpusReferences":[]}]},"conversationSummary":"...","conversationState":{"lessonTitle":"Tracing Loops","lessonDuration":"45","sectionCount":1}}
lesson-to-assessment-package-v1 Generate a persistence-shaped assessment package from a complete lesson and assessment policy. request · response {"localeCode":"en_US","lesson":{"title":"Tracing Loops","sections":[{"title":"Loop Conditions","content":"..."}]},"assessmentPolicy":{"targetAssessmentCount":3,"allowedStrategies":["sync","aiSync"],"aiGraderResourceURN":"urn:ayode:resource:/codermerlin.academy/system/ai/grade-short-freeform@1"}} {"version":1,"packageType":"lessonAssessmentPackage","localeCode":"en_US","assignmentNameJTO":{"en_US":"Tracing Loops Assessment"},"assessments":[{"sortOrder":1,"isRequired":true,"challengeNameJTO":{"en_US":"Loop Condition Check"},"variant":{"evaluationStrategy":"sync","localeCode":"en_US","queriesMPlusM":"...","responsesJSON":{"version":1,"evaluationMode":"textEquivalence","acceptedResponses":["..."]}}}],"coverageSummary":"...","conversationSummary":"...","conversationState":{"lessonTitle":"Tracing Loops","assessmentCount":1,"strategiesUsed":["sync"],"localeCode":"en_US"}}
lesson-outline-to-lesson-v1 Expand one section of a lesson outline into full lesson content. request · response {"outline":{"title":"Tracing Loops","sections":[{"title":"Loop Conditions","sectionType":"instruction","durationMinutes":10}]},"currentSectionIndex":0,"knowledge":[{"id":"k1","title":"Loop Condition","description":"..."}],"reasoning":[{"id":"r1","title":"Trace Iterations","description":"..."}],"performance":[{"id":"e1","title":"Write a Loop","description":"..."}],"rootRealmEIDurn":"urn:ayode:realm-eid:00000000-0000-0000-0000-000000000000"} {"section":{"sectionType":"instruction","title":"Loop Conditions","durationMinutes":10,"content":"...","activities":[{"title":"Trace It","instructions":"..."}]},"contentSummary":"...","conversationSummary":"...","conversationState":{"completedSectionIndex":0,"sectionTitle":"Loop Conditions"}}
markdown-to-fill-in-the-blank-assessments-v1 Generate fill-in-the-blank assessment items grounded only in supplied Markdown. request · response {"sourceDocumentName":"loops.md","sectionTitle":"Loop Basics","markdown":"# Loop Basics\nA loop repeats instructions while a condition is true.","localeCode":"en_US","targetQuestionCount":2} {"sourceDocumentName":"loops.md","sectionTitle":"Loop Basics","localeCode":"en_US","questionType":"fillInTheBlank","assessments":[{"id":"assessment-001","sourceHeadings":["Loop Basics"],"display":{"promptMarkdown":"A loop repeats instructions while a condition is _____.","acceptedResponses":["true"]},"assessment":{"sortOrder":1,"isRequired":true,"challengeNameJTO":{"en_US":"Loop Condition"},"variant":{"evaluationStrategy":"sync","localeCode":"en_US","queriesMPlusM":"...","responsesJSON":{"version":1,"evaluationMode":"textEquivalence","acceptedResponses":["true"]}}}}],"coverageSummary":"...","conversationSummary":"...","conversationState":{"sourceDocumentName":"loops.md","sectionTitle":"Loop Basics","questionCount":1,"localeCode":"en_US","questionType":"fillInTheBlank"}}
markdown-to-questions-and-answers-v1 Generate study question-and-answer pairs grounded only in supplied Markdown. request · response {"sourceDocumentName":"loops.md","markdown":"# Loop Basics\nA loop repeats instructions while a condition is true."} {"sourceDocumentName":"loops.md","questionsAndAnswers":[{"id":"qa-001","question":"What does a loop do?","answer":"It repeats instructions while a condition is true.","sourceHeadings":["Loop Basics"]}],"coverageSummary":"...","truncated":false,"conversationSummary":"...","conversationState":{"sourceDocumentName":"loops.md","questionCount":1,"truncated":false,"coveredHeadings":["Loop Basics"]}}
markdown-to-single-select-assessments-v1 Generate single-select assessment items grounded only in supplied Markdown. request · response {"sourceDocumentName":"loops.md","sectionTitle":"Loop Basics","markdown":"# Loop Basics\nA loop repeats instructions while a condition is true.","localeCode":"en_US","targetQuestionCount":2} {"sourceDocumentName":"loops.md","sectionTitle":"Loop Basics","localeCode":"en_US","questionType":"singleSelect","assessments":[{"id":"assessment-001","sourceHeadings":["Loop Basics"],"display":{"promptMarkdown":"When does the loop repeat?","options":[{"token":"A","text":"While the condition is true"},{"token":"B","text":"Only once"}],"correctOptionToken":"A"},"assessment":{"sortOrder":1,"isRequired":true,"challengeNameJTO":{"en_US":"Loop Condition"},"variant":{"evaluationStrategy":"sync","localeCode":"en_US","queriesMPlusM":"...","responsesJSON":{"version":1,"evaluationMode":"singleSelect","acceptedResponse":"A"}}}}],"coverageSummary":"...","conversationSummary":"...","conversationState":{"sourceDocumentName":"loops.md","sectionTitle":"Loop Basics","questionCount":1,"localeCode":"en_US","questionType":"singleSelect"}}

Version 2 (-v2) generation — gpt-5.1

Every public human name in this document now also exists in a -v2 variant (#2343): the same operation republished as its @2 bundle. For each name, replace the -v1 suffix with -v2 (e.g. lesson-text-tune-content-simplify-v2, curriculum-topics-to-activities-v2). The -v2 variants:

Instructor Studio AI Tune (v2)

These human names back the Instructor Studio “AI Tune” feature: an instructor selects a passage of lesson text and requests a targeted transformation. The 25 selection-scoped bundles share one request/response contract, so they are listed together rather than repeating the same sample JSON 25 times. A separate group of 3 whole-lesson Generate bundles (-whole-lesson-v1, see the whole-lesson table below) uses a distinct, marker-free request contract described in its own section:

Human name Category Endpoint RAG Function
lesson-text-tune-content-explain-more-v1 Content async yes Expand the selection with additional explanation, adding depth without changing its core meaning.
lesson-text-tune-content-simplify-v1 Content sync no Reduce complexity and vocabulary level while preserving meaning.
lesson-text-tune-content-make-more-concise-v1 Content sync no Shorten the selection while preserving essential meaning.
lesson-text-tune-content-increase-technical-depth-v1 Content async yes Add technical precision and detail for a more advanced learner.
lesson-text-tune-content-add-example-v1 Content async yes Add a concrete worked example illustrating the concept.
lesson-text-tune-content-add-analogy-v1 Content async yes Add an analogy that clarifies the concept.
lesson-text-tune-clarity-improve-flow-v1 Clarity sync no Improve sentence/paragraph flow and transitions without changing meaning.
lesson-text-tune-clarity-improve-grammar-v1 Clarity sync no Fix grammar and mechanics only, with minimal wording changes otherwise.
lesson-text-tune-clarity-clarify-terminology-v1 Clarity sync no Clarify ambiguous or undefined terms in place.
lesson-text-tune-clarity-improve-accessibility-v1 Clarity sync no Improve plain-language accessibility (reading level, jargon).
lesson-text-tune-pedagogy-adapt-younger-v1 Pedagogy sync no Rewrite for a younger audience’s vocabulary and framing.
lesson-text-tune-pedagogy-adapt-older-v1 Pedagogy sync no Rewrite for an older, more advanced audience.
lesson-text-tune-pedagogy-increase-engagement-v1 Pedagogy sync no Rewrite to be more engaging (hooks, relatable framing).
lesson-text-tune-pedagogy-socratic-style-v1 Pedagogy sync no Rewrite as guiding questions rather than direct statements.
lesson-text-tune-style-more-conversational-v1 Style sync no Shift voice to be more conversational and informal.
lesson-text-tune-style-more-formal-v1 Style sync no Shift voice to be more formal and academic.
lesson-text-tune-style-more-enthusiastic-v1 Style sync no Shift voice to be more energetic and enthusiastic.
lesson-text-tune-style-more-neutral-v1 Style sync no Shift voice to be neutral and matter-of-fact.
lesson-text-tune-generate-summary-v1 Generate sync no Generate a concise summary of the selection as new material.
lesson-text-tune-generate-learning-objectives-v1 Generate async yes Generate learning objectives derived from the selection as new material.
lesson-text-tune-generate-key-takeaways-v1 Generate sync no Generate key-takeaway bullet points derived from the selection as new material.
lesson-text-tune-generate-practice-questions-v1 Generate async yes Generate practice questions covering the selection as new material.
lesson-text-tune-generate-challenge-questions-v1 Generate async yes Generate harder, extension-level questions covering the selection as new material.
lesson-text-tune-generate-glossary-definition-v1 Generate sync no Generate a definition of the selected term, matched to the lesson’s language level, as new material.
lesson-text-tune-custom-v1 Custom async yes Follow the instructor’s free-form instruction field for any transformation not covered above.

Per-bundle request/response schemas: ../apis.html#/schemas/LessonTextTune<PascalOperation>V1Request / ...Response, e.g. request · response for lesson-text-tune-content-explain-more-v1.

Whole-lesson Generate variants (marker-free)

A separate group of 3 Generate bundles operates on the entire lesson rather than a selected passage. They back Instructor Studio’s top-level Lesson ▸ ĀYŌDÈ Intelligence menu, which generates or updates a dedicated Summary / Learning Objectives / Key Takeaways panel for the whole lesson. Unlike the 25 selection-scoped bundles above, their request contract carries no selection markers — the whole lessonText is in scope:

Human name Category Endpoint RAG Function
lesson-text-tune-generate-summary-whole-lesson-v1 Generate sync no Generate a concise summary of the entire lesson as new material for a standalone panel.
lesson-text-tune-generate-learning-objectives-whole-lesson-v1 Generate async yes Generate learning objectives covering the entire lesson as new material for a standalone panel.
lesson-text-tune-generate-key-takeaways-whole-lesson-v1 Generate sync no Generate key-takeaway bullet points covering the entire lesson as new material for a standalone panel.

Per-bundle request/response schemas follow the same PascalCase naming, e.g. request · response for lesson-text-tune-generate-summary-whole-lesson-v1.

Instructor Studio assessment-panel generation (RAG, whole-lesson) (#2539)

A separate group of 3 human names backs Instructor Studio’s context-menu ĀYŌDÈ Intelligence ▸ Generate/update assessment panel feature: an instructor generates reviewable assessment items for the current panel (or a selected passage) that are hydrated into a child assessment panel and a mission. Unlike the section-scoped markdown-to-*-assessments bundles, these are RAG-enabled and take the entire lesson text as tuning context in addition to the scoped generation source. casEquivalence (Math expression) is deferred for the first POC, so there are three bundles (one per question family):

Human name Question family Endpoint RAG Function
lesson-assessment-fill-in-the-blank-v1 fillInTheBlank async yes Generate fill-in-the-blank assessments grounded in the scoped source, tuned against the whole lesson.
lesson-assessment-single-select-v1 singleSelect async yes Generate single-answer multiple-choice assessments grounded in the scoped source, tuned against the whole lesson.
lesson-assessment-multiple-select-v1 multipleSelect async yes Generate multiple-answer multiple-choice assessments grounded in the scoped source, tuned against the whole lesson.

Per-bundle request/response schemas follow the same PascalCase naming, e.g. request · response for lesson-assessment-multiple-select-v1.

Orchestration Jobs

Long-running workflows use job-style APIs rather than synchronous request/response patterns.

Expect these concepts:

Client responsibilities:

jobAsync Challenge Grading

jobAsync is a challenge-grading strategy that executes a student’s submitted code and compares its output against instructor-authored expected output, using the platform’s job-orchestration system, instead of AI grading (aiSync/aiAsync) or an exact-match responsesJSON check.

Current availability. Authoring a jobAsync challenge variant is live today via createChallengeVariantForChallengeV2. Starting an attempt against one is not yet available: createChallengeAttemptV2 and createChallengeTestV2 both return 422 UnprocessableEntity_JobAsyncExecutionNotYetAvailable for every otherwise-valid jobAsync request until real job-orchestration content ships.

The mechanism, at a glance:

flowchart LR
    A[Generator bundle] -->|produces test input\nand expected output| B[Student's submitted code runs]
    B -->|produces the student's output| C[Comparator bundle]
    A -->|expected output| C
    C -->|awarded score + feedback| D[ChallengeResult]

A variant references its generator and comparator bundles by digest (generatorBundleDigest/comparatorBundleDigest), obtained by uploading each bundle to the job-execution-content store first (initializeExecutionContentUploadV2 for large bundles, or uploadJobExecutionContentBundleV2 for bundles up to 4 MiB) and then passing the returned digest into createChallengeVariantForChallengeV2. A variant may instead select one of the platform’s built-in standard comparators via evaluationConfigJSON.comparator, in which case comparatorBundleDigest may be omitted entirely (#4649) — generatorBundleDigest is always required regardless.

See Appendix II: jobAsync Generator/Comparator Bundle Contracts for the exact file format a generator/comparator bundle must produce, how bundle content is kept private from the student, and the orchestration/run-command format used for more comprehensive, explicit-invocation authoring.

Once attempt execution is available, a failed jobAsync attempt’s classified failure reason surfaces on the attempt itself as ChallengeAttempt’s failureCategory/failureMessage.

Gaming

The gaming APIs model competitive structures such as:

These endpoints share common relationship patterns. Clients should expect team, season, and game operations to be connected rather than independent.

Third-Party Connections

The current overview focus is Google Drive integration.

Typical browser flow:

OAuth and import details remain endpoint-specific and are documented in the sidebar under Connections > Google.

Where To Go Next