{"info":{"_postman_id":"630598da-34e4-498c-8518-31de9823a4e2","name":"Developer requests","description":"

A collection of API requests for interacting with Learngual's development tools to build robust language learning applications.

\n

Don't have an account? Click to get Started

\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[],"owner":"30010546","collectionId":"630598da-34e4-498c-8518-31de9823a4e2","publishedId":"2s9YJW6mES","public":true,"customColor":{"top-bar":"FFF9E7","right-sidebar":"000","highlight":"099"},"publishDate":"2024-02-26T20:21:40.000Z"},"item":[{"name":"Learngual API integration","item":[{"name":"Speech analysis","item":[{"name":"Speech analysis","event":[{"listen":"test","script":{"id":"2038250b-6bf9-4a8f-a9f5-fc4c33c57d4a","exec":["json = pm.response.json()","","if (json?.task_id){"," pm.collectionVariables.set(\"task_id\",json.task_id)","}"],"type":"text/javascript","packages":{}}},{"listen":"prerequest","script":{"id":"f8ad67ef-a95c-4fc4-8010-0964daf651fb","exec":[""],"type":"text/javascript","packages":{}}}],"id":"d1a7e8d2-2127-48c8-92ab-1954d3c0e08a","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[{"key":"api-key","value":"{{api-key}}"}],"body":{"mode":"formdata","formdata":[{"key":"reference_text","value":"administration","description":"

only optional if unscripted is false

\n","type":"text"},{"key":"audio_data","type":"file","src":"postman-cloud:///1eed2266-4031-4d60-8db3-031c829325ed"},{"key":"language","value":"English","description":"

optional: fr, en

\n","type":"text"},{"key":"scripted","value":"true","description":"

optional:

\n","type":"text"},{"key":"prompt","value":"Tell me about your holiday.","description":"

optional:

\n","type":"text","disabled":true},{"key":"callback_url","value":"http://gabriel.net","type":"text","disabled":true},{"key":"correct_reference","value":"true","type":"text","uuid":"1fd33d4a-13fe-4678-a3a3-be6614f65ed6","disabled":true}]},"url":"{{url}}/speech-analysis/","description":"

Purpose

\n

Submits an audio file to the speech service for transcription and analysis.

\n

This endpoint is called using multipart/form-data, meaning the audio is sent inside the HTTP request body as a file field named audio_data, along with additional form fields that control processing behavior.

\n

The scripted field determines the processing mode:

\n\n

If callback_url is provided, results may be delivered asynchronously to that URL once processing completes.

\n
\n

Request format

\n\n
\n

Request body fields

\n

audio_data

\n\n

language

\n\n

scripted

\n\n

reference_text

\n\n

correct_reference

\n\n

prompt

\n\n

callback_url

\n\n
\n

Processing modes

\n

Scripted mode (scripted=true)

\n

Use this mode when you want to measure how closely the speaker’s audio matches a known expected text.

\n

Requirements

\n\n

Behavior

\n\n
\n

Unscripted mode (scripted=false)

\n

Use this mode when you want a free transcription without a provided script.

\n

Requirements

\n\n

Behavior

\n\n
\n

Validation rules and constraints

\n\n","urlObject":{"path":["speech-analysis",""],"host":["{{url}}"],"query":[{"disabled":true,"key":"api-key","value":"{{api-key}}"}],"variable":[]}},"response":[{"id":"17d387f5-8635-4d09-a6fa-0734d312ee1c","name":"Speech analysis","originalRequest":{"method":"POST","header":[{"key":"account","value":"{{account_id}}","description":"231e2ac390","disabled":true},{"key":"api-key","value":"","disabled":true},{"key":"api-key","value":"{{api-key}}"}],"body":{"mode":"formdata","formdata":[{"key":"reference_text","value":"administration","description":"only optional if unscripted is false","type":"text"},{"key":"audio_data","type":"file","src":"postman-cloud:///1eed2266-4031-4d60-8db3-031c829325ed"},{"key":"language","value":"English","description":"optional: fr, en","type":"text"},{"key":"scripted","value":"true","description":"optional: ","type":"text"},{"key":"prompt","value":"Tell me about your holiday.","description":"optional: ","type":"text","disabled":true},{"key":"callback_url","value":"http://billy.com","type":"text","disabled":true},{"key":"correct_reference","value":"true","type":"text","uuid":"1fd33d4a-13fe-4678-a3a3-be6614f65ed6","disabled":true}]},"url":{"raw":"{{url}}/speech-analysis/","host":["{{url}}"],"path":["speech-analysis",""],"query":[{"key":"api-key","value":"{{api-key}}","disabled":true}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Server","value":"nginx/1.18.0 (Ubuntu)"},{"key":"Date","value":"Sun, 21 Dec 2025 19:19:37 GMT"},{"key":"Content-Type","value":"application/json","description":""},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Vary","value":"Accept-Encoding"},{"key":"Vary","value":"Accept, Accept-Language, Cookie, origin"},{"key":"Allow","value":"POST, OPTIONS"},{"key":"X-Frame-Options","value":"DENY"},{"key":"Content-Language","value":"en"},{"key":"Strict-Transport-Security","value":"max-age=60; includeSubDomains; preload"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"Referrer-Policy","value":"same-origin"},{"key":"Cross-Origin-Opener-Policy","value":"same-origin"},{"key":"Content-Encoding","value":"gzip"}],"cookie":[],"responseTime":null,"body":"{\n \"Reference\": \"administration\",\n \"Hypothesis\": \"administration\",\n \"General Score\": 92,\n \"Speech Rate\": 78.94736842105263,\n \"Audibility\": 86.36084909836867,\n \"Word Phonetic Evaluation\": {\n \"1\": {\n \"Word\": \"ADMINISTRATION\",\n \"Word Meaning\": [],\n \"Synonyms\": [],\n \"Antonyms\": [],\n \"Syllables\": [\n {\n \"Onset\": \"EMPTY\",\n \"Nucleus\": \"AE\",\n \"Coda\": \"D\",\n \"isShort\": true,\n \"isLight\": false,\n \"Stress\": \"No\",\n \"Syllabic Score\": 100\n },\n {\n \"Onset\": \"M\",\n \"Nucleus\": \"IH\",\n \"Coda\": \"EMPTY\",\n \"isShort\": true,\n \"isLight\": true,\n \"Stress\": \"Secondary\",\n \"Syllabic Score\": 100\n },\n {\n \"Onset\": \"N\",\n \"Nucleus\": \"IH\",\n \"Coda\": \"EMPTY\",\n \"isShort\": true,\n \"isLight\": true,\n \"Stress\": \"No\",\n \"Syllabic Score\": 100\n },\n {\n \"Onset\": \"STR\",\n \"Nucleus\": \"EY\",\n \"Coda\": \"EMPTY\",\n \"isShort\": false,\n \"isLight\": false,\n \"Stress\": \"Primary\",\n \"Syllabic Score\": 100\n },\n {\n \"Onset\": \"SH\",\n \"Nucleus\": \"AH\",\n \"Coda\": \"N\",\n \"isShort\": true,\n \"isLight\": false,\n \"Stress\": \"No\",\n \"Syllabic Score\": 99\n }\n ],\n \"Word Score\": 100,\n \"Number Of Syllables\": 5,\n \"Phoneme Phonetic Evaluation\": {\n \"1\": {\n \"Phoneme (Grapheme)\": \"AE\",\n \"Score\": 100,\n \"Duration\": \"0.05 secs\",\n \"Grade\": \"Excellent\",\n \"Phoneme Feedback Summary\": \"Perfect pronunciation!\",\n \"Phoneme Feedback\": \"The 'AE' sound was pronounced with perfect clarity and accuracy.\",\n \"Phoneme\": \"AE\",\n \"IPA\": \"æ\",\n \"Example\": \"at\",\n \"Translation\": \"AE T\",\n \"Class\": \"VOWEL\",\n \"Voice\": \"VOICED\",\n \"Articulator\": \"\",\n \"Airstream Mechanism\": \"\",\n \"Other Examples\": [\n \"videocassette\",\n \"blanken\",\n \"harring\",\n \"caltrain\",\n \"mollohan\",\n \"lana\",\n \"forecasted\",\n \"salmond\",\n \"slashes\",\n \"uliassi's\",\n \"magazine's\"\n ]\n },\n \"2\": {\n \"Phoneme (Grapheme)\": \"D\",\n \"Score\": 100,\n \"Duration\": \"0.07 secs\",\n \"Grade\": \"Excellent\",\n \"Phoneme Feedback Summary\": \"Perfect pronunciation!\",\n \"Phoneme Feedback\": \"The 'D' sound was pronounced with perfect clarity and accuracy.\",\n \"Phoneme\": \"D\",\n \"IPA\": \"d\",\n \"Example\": \"dee\",\n \"Translation\": \"D IY\",\n \"Class\": \"STOP (CONSONANT)\",\n \"Voice\": \"VOICED\",\n \"Articulator\": \"ALVEOLAR\",\n \"Airstream Mechanism\": \"PLOSIVE\",\n \"Other Examples\": [\n \"seinfeld\",\n \"allowed\",\n \"hinted\",\n \"forebode\",\n \"doctors\",\n \"yandle\",\n \"high-spiritedness\",\n \"dullest\",\n \"pandered\",\n \"diversionary\",\n \"cold-blooded\"\n ]\n },\n \"3\": {\n \"Phoneme (Grapheme)\": \"M\",\n \"Score\": 100,\n \"Duration\": \"0.07 secs\",\n \"Grade\": \"Excellent\",\n \"Phoneme Feedback Summary\": \"Perfect pronunciation!\",\n \"Phoneme Feedback\": \"The 'M' sound was pronounced with perfect clarity and accuracy.\",\n \"Phoneme\": \"M\",\n \"IPA\": \"m\",\n \"Example\": \"me\",\n \"Translation\": \"M IY\",\n \"Class\": \"NASAL (CONSONANT)\",\n \"Voice\": \"VOICED\",\n \"Articulator\": \"BILABIAL\",\n \"Airstream Mechanism\": \"NASAL\",\n \"Other Examples\": [\n \"yogiisms\",\n \"misprint\",\n \"immunities\",\n \"macrame\",\n \"elmootazbellah\",\n \"minstrels\",\n \"muehlbauer\",\n \"backgammon\",\n \"predominance\",\n \"broomstick\",\n \"melodramatic\"\n ]\n },\n \"4\": {\n \"Phoneme (Grapheme)\": \"IH\",\n \"Score\": 100,\n \"Duration\": \"0.06 secs\",\n \"Grade\": \"Excellent\",\n \"Phoneme Feedback Summary\": \"Perfect pronunciation!\",\n \"Phoneme Feedback\": \"The 'IH' sound was pronounced with perfect clarity and accuracy.\",\n \"Phoneme\": \"IH\",\n \"IPA\": \"i\",\n \"Example\": \"it\",\n \"Translation\": \"IH T\",\n \"Class\": \"VOWEL\",\n \"Voice\": \"VOICED\",\n \"Articulator\": \"\",\n \"Airstream Mechanism\": \"\",\n \"Other Examples\": [\n \"cowlicks\",\n \"finances\",\n \"assassinating\",\n \"polymerase\",\n \"averted\",\n \"distrustful\",\n \"illiquid\",\n \"leadership\",\n \"imbued\",\n \"witucki\",\n \"intellectual\"\n ]\n },\n \"5\": {\n \"Phoneme (Grapheme)\": \"N\",\n \"Score\": 100,\n \"Duration\": \"0.05 secs\",\n \"Grade\": \"Excellent\",\n \"Phoneme Feedback Summary\": \"Perfect pronunciation!\",\n \"Phoneme Feedback\": \"The 'N' sound was pronounced with perfect clarity and accuracy.\",\n \"Phoneme\": \"N\",\n \"IPA\": \"n\",\n \"Example\": \"knee\",\n \"Translation\": \"N IY\",\n \"Class\": \"NASAL (CONSONANT)\",\n \"Voice\": \"VOICED\",\n \"Articulator\": \"ALVEOLAR\",\n \"Airstream Mechanism\": \"NASAL\",\n \"Other Examples\": [\n \"pennebaker\",\n \"oriana\",\n \"saccomanno\",\n \"keleman\",\n \"canary\",\n \"hauenstein\",\n \"lemans\",\n \"prominence\",\n \"merline\",\n \"valentina\",\n \"finest\"\n ]\n },\n \"6\": {\n \"Phoneme (Grapheme)\": \"IH\",\n \"Score\": 100,\n \"Duration\": \"0.05 secs\",\n \"Grade\": \"Excellent\",\n \"Phoneme Feedback Summary\": \"Perfect pronunciation!\",\n \"Phoneme Feedback\": \"The 'IH' sound was pronounced with perfect clarity and accuracy.\",\n \"Phoneme\": \"IH\",\n \"IPA\": \"i\",\n \"Example\": \"it\",\n \"Translation\": \"IH T\",\n \"Class\": \"VOWEL\",\n \"Voice\": \"VOICED\",\n \"Articulator\": \"\",\n \"Airstream Mechanism\": \"\",\n \"Other Examples\": [\n \"grim\",\n \"lincare\",\n \"nichols\",\n \"nutting\",\n \"gobbling\",\n \"yanish\",\n \"conditional\",\n \"pictet\",\n \"indianapolis's\",\n \"presages\",\n \"abramovitz\"\n ]\n },\n \"7\": {\n \"Phoneme (Grapheme)\": \"S\",\n \"Score\": 100,\n \"Duration\": \"0.1 secs\",\n \"Grade\": \"Excellent\",\n \"Phoneme Feedback Summary\": \"Perfect pronunciation!\",\n \"Phoneme Feedback\": \"The 'S' sound was pronounced with perfect clarity and accuracy.\",\n \"Phoneme\": \"S\",\n \"IPA\": \"s\",\n \"Example\": \"sea\",\n \"Translation\": \"S IY\",\n \"Class\": \"FRICATIVE (CONSONANT)\",\n \"Voice\": \"VOICELESS\",\n \"Articulator\": \"ALVEOLAR\",\n \"Airstream Mechanism\": \"FRICATIVE\",\n \"Other Examples\": [\n \"scuttled\",\n \"businessland\",\n \"jelinski\",\n \"ancients\",\n \"sensitized\",\n \"smith's\",\n \"inaugurates\",\n \"phylis\",\n \"seratonin\",\n \"cousteau\",\n \"serviced\"\n ]\n },\n \"8\": {\n \"Phoneme (Grapheme)\": \"T\",\n \"Score\": 100,\n \"Duration\": \"0.05 secs\",\n \"Grade\": \"Excellent\",\n \"Phoneme Feedback Summary\": \"Perfect pronunciation!\",\n \"Phoneme Feedback\": \"The 'T' sound was pronounced with perfect clarity and accuracy.\",\n \"Phoneme\": \"T\",\n \"IPA\": \"t\",\n \"Example\": \"tea\",\n \"Translation\": \"T IY\",\n \"Class\": \"STOP (CONSONANT)\",\n \"Voice\": \"VOICELESS\",\n \"Articulator\": \"ALVEOLAR\",\n \"Airstream Mechanism\": \"PLOSIVE\",\n \"Other Examples\": [\n \"blancett\",\n \"thai's\",\n \"eisenhardt\",\n \"centralia\",\n \"angert\",\n \"passaretti\",\n \"lufttransport\",\n \"ratcliff\",\n \"obtained\",\n \"fingerpointing\",\n \"electricar\"\n ]\n },\n \"9\": {\n \"Phoneme (Grapheme)\": \"R\",\n \"Score\": 100,\n \"Duration\": \"0.05 secs\",\n \"Grade\": \"Excellent\",\n \"Phoneme Feedback Summary\": \"Perfect pronunciation!\",\n \"Phoneme Feedback\": \"The 'R' sound was pronounced with perfect clarity and accuracy.\",\n \"Phoneme\": \"R\",\n \"IPA\": \"ɹ\",\n \"Example\": \"read\",\n \"Translation\": \"R IY D\",\n \"Class\": \"LIQUID (CONSONANT)\",\n \"Voice\": \"VOICED\",\n \"Articulator\": \"ALVEOLAR\",\n \"Airstream Mechanism\": \"CENTRAL\",\n \"Other Examples\": [\n \"harbor\",\n \"unimproved\",\n \"roquemore\",\n \"bruce's\",\n \"breakneck\",\n \"retaliated\",\n \"koruna\",\n \"rawson\",\n \"hair\",\n \"disparage\",\n \"brennen\"\n ]\n },\n \"10\": {\n \"Phoneme (Grapheme)\": \"EY\",\n \"Score\": 99,\n \"Duration\": \"0.08 secs\",\n \"Grade\": \"Excellent\",\n \"Phoneme Feedback Summary\": \"Perfect pronunciation!\",\n \"Phoneme Feedback\": \"The 'EY' sound was pronounced with perfect clarity and accuracy.\",\n \"Phoneme\": \"EY\",\n \"IPA\": \"eɪ\",\n \"Example\": \"ate\",\n \"Translation\": \"EY T\",\n \"Class\": \"VOWEL\",\n \"Voice\": \"VOICED\",\n \"Articulator\": \"\",\n \"Airstream Mechanism\": \"\",\n \"Other Examples\": [\n \"rainy\",\n \"operations\",\n \"akin\",\n \"brattain\",\n \"aggravated\",\n \"cases\",\n \"naivete\",\n \"frustratingly\",\n \"educationally\",\n \"inflames\",\n \"bather\"\n ]\n },\n \"11\": {\n \"Phoneme (Grapheme)\": \"SH\",\n \"Score\": 100,\n \"Duration\": \"0.15 secs\",\n \"Grade\": \"Excellent\",\n \"Phoneme Feedback Summary\": \"Perfect pronunciation!\",\n \"Phoneme Feedback\": \"The 'SH' sound was pronounced with perfect clarity and accuracy.\",\n \"Phoneme\": \"SH\",\n \"IPA\": \"ʃ\",\n \"Example\": \"she\",\n \"Translation\": \"SH IY\",\n \"Class\": \"FRICATIVE (CONSONANT)\",\n \"Voice\": \"VOICELESS\",\n \"Articulator\": \"POSTALVEOLAR\",\n \"Airstream Mechanism\": \"FRICATIVE\",\n \"Other Examples\": [\n \"cliched\",\n \"mondschein\",\n \"crocheted\",\n \"shasteen\",\n \"washed\",\n \"shipe\",\n \"adoptions\",\n \"interpretations\",\n \"schippers\",\n \"bouchard\",\n \"sramek\"\n ]\n },\n \"12\": {\n \"Phoneme (Grapheme)\": \"AH\",\n \"Score\": 99,\n \"Duration\": \"0.13 secs\",\n \"Grade\": \"Excellent\",\n \"Phoneme Feedback Summary\": \"Perfect pronunciation!\",\n \"Phoneme Feedback\": \"The 'AH' sound was pronounced with perfect clarity and accuracy.\",\n \"Phoneme\": \"AH\",\n \"IPA\": \"ʌ\",\n \"Example\": \"hut\",\n \"Translation\": \"HH AH T\",\n \"Class\": \"VOWEL\",\n \"Voice\": \"VOICED\",\n \"Articulator\": \"\",\n \"Airstream Mechanism\": \"\",\n \"Other Examples\": [\n \"borja\",\n \"pyramid\",\n \"saracens\",\n \"jaekel\",\n \"attridge\",\n \"biotite\",\n \"socialist\",\n \"buxom\",\n \"touchton\",\n \"simulators\",\n \"undiplomatic\"\n ]\n },\n \"13\": {\n \"Phoneme (Grapheme)\": \"N\",\n \"Score\": 99,\n \"Duration\": \"0.15 secs\",\n \"Grade\": \"Excellent\",\n \"Phoneme Feedback Summary\": \"Perfect pronunciation!\",\n \"Phoneme Feedback\": \"The 'N' sound was pronounced with perfect clarity and accuracy.\",\n \"Phoneme\": \"N\",\n \"IPA\": \"n\",\n \"Example\": \"knee\",\n \"Translation\": \"N IY\",\n \"Class\": \"NASAL (CONSONANT)\",\n \"Voice\": \"VOICED\",\n \"Articulator\": \"ALVEOLAR\",\n \"Airstream Mechanism\": \"NASAL\",\n \"Other Examples\": [\n \"gettinger\",\n \"sprained\",\n \"koon\",\n \"vacillation\",\n \"newhouse\",\n \"mercantilist\",\n \"bonfiglio\",\n \"centeno\",\n \"gonna\",\n \"novo's\",\n \"laminating\"\n ]\n }\n }\n }\n },\n \"CEFR Score\": \"C2\",\n \"CEFR Feedback\": \"Excellent pronunciation skills demonstrated. Minor stress and phonetic refinements will perfect the speech delivery, showing remarkable progress.\",\n \"Fluency\": 96,\n \"Intonation\": 100,\n \"Scripted\": true,\n \"Prompt\": \"\",\n \"Language\": \"en\",\n \"TOEFL iBT Score\": 27,\n \"TOEFL iBT Total Score\": 30,\n \"IELTS Score\": 8,\n \"IELTS Total Score\": 9,\n \"PTE Score\": 81,\n \"PTE Total Score\": 90,\n \"TOEIC Score\": 181,\n \"TOEIC Total Score\": 200,\n \"TOEFL iBT Feedback\": \"Outstanding clarity and fluidity demonstrated. While not quite perfect, this shows excellent command of pronunciation and intonation. Minor refinements will achieve top-level performance. Outstanding work is evident. Speech shows excellent control of stress and intonation patterns. The art of using pitch and emphasis to enhance the message has been mastered - exactly what the TOEFL seeks. Wonderful performance. Speech flows perfectly with natural and appropriate pauses. Excellent control over speaking rhythm has been achieved.\",\n \"IELTS Feedback\": \"Outstanding pronunciation work demonstrated. The speech is very easy to follow, with only minor areas needing improvement. Continue polishing these final details. Outstanding work is demonstrated. Speech shows perfect fluency with natural pauses that enhance the message beautifully.\",\n \"PTE Feedback\": \"Impressive score achieved. Clarity and pronunciation are strong, though small details can still be perfected. Very close to complete mastery. Fantastic performance is achieved. Command of stress and intonation is exactly what the PTE rewards. Clear and effective communication is demonstrated, using natural rhythm and appropriate emphasis. This is a model example of what clear, engaging speech should sound like. Exceptional achievement is evident. Speaking rhythm shows perfect control and natural flow throughout.\",\n \"TOEIC Feedback\": \"Nearly perfect performance achieved. Pronunciation and fluency are excellent. Additional practice on specific areas will complete mastery of workplace communication.\"\n}"}],"_postman_id":"d1a7e8d2-2127-48c8-92ab-1954d3c0e08a"}],"id":"065b7275-111f-42e4-82aa-fce686895cb8","_postman_id":"065b7275-111f-42e4-82aa-fce686895cb8","description":"","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"76df429f-1521-446e-9869-5169c05928cc","id":"76df429f-1521-446e-9869-5169c05928cc","name":"Learngual API integration","type":"folder"}}},{"name":"Language logic","item":[{"name":"Check language logic","id":"7073ec6f-3dc3-4450-8d12-4cf3cb8a4a9b","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"api-key","value":"{{api-key}}"}],"body":{"mode":"raw","raw":"{\n \"topic\": \"My First Day at Work\",\n \"essay\": \"nothing hapened\",\n \"criteria\": [\n \"evidence\",\n \"coherence\",\n \"relevance\",\n \"critical_thinking\"\n ]\n}","options":{"raw":{"language":"json"}}},"url":"{{url}}/essay_evaluation/","description":"

Essay Evaluation API

\n

Endpoint:
POST {{url}}/essay_evaluation/

\n

Purpose

\n

This endpoint evaluates an essay against a given topic using multiple assessment criteria.
It provides general feedback and delivers criteria-specific insights with example improvements.
The API is useful for automated grading, skill improvement feedback, and structured essay reviews.

\n
\n

Request Method

\n

POST

\n
\n

Request Body

\n

Send the body as JSON.

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldTypeRequiredDescription
topicstringYesThe essay's target topic or subject.
essaystringYesThe essay text to be evaluated.
criteriaarray of stringsNoSpecific evaluation aspects to assess. Examples: \"evidence\", \"coherence\", \"relevance\", \"critical_thinking\". If omitted, the system uses default evaluation criteria.
\n
\n

Example Request

\n
{\n    \"topic\": \"My First Day at Work\",\n    \"essay\": \"nothing hapened\",\n    \"criteria\": [\n        \"evidence\",\n        \"coherence\",\n        \"relevance\",\n        \"critical_thinking\"\n    ]\n}\n\n
\n
\n

Response

\n

The API returns a compiled narrative covering all criteria feedback, along with a breakdown for each criterion.

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldTypeDescription
overall_feedbackstringA compiled narrative covering all criteria feedback in one detailed section.
char_countnumberTotal number of characters in the topic + essay.
word_countnumberTotal number of words in the essay.
criteriaobjectA breakdown of each criterion with its own feedback, improvement example, and optional rating.
\n
\n

Example Response

\n
{\n    \"overall_feedback\": \"Evidence: The essay lacks any form of evidence or supporting details... \\n\\nCoherence: The essay lacks coherence... \\n\\nRelevance: The essay does not address the topic... \\n\\nCritical Thinking: The essay lacks any form of analysis...\",\n    \"char_count\": 15,\n    \"word_count\": 2,\n    \"criteria\": {\n        \"evidence\": {\n            \"feedback\": \"The essay lacks any form of evidence or supporting details...\",\n            \"example\": \"<IMPROVEMENT>\\nMy first day at work was a memorable experience... \\n</IMPROVEMENT>\"\n        },\n        \"coherence\": {\n            \"feedback\": \"The essay lacks coherence as it does not provide any content...\",\n            \"example\": \"<IMPROVEMENT>\\nMy First Day at Work\\n\\nI still remember my first day...\\n</IMPROVEMENT>\"\n        },\n        \"relevance\": {\n            \"feedback\": \"The essay does not address the topic at all...\",\n            \"example\": \"<IMPROVEMENT>My first day at work was a memorable experience...</IMPROVEMENT>\",\n            \"rating\": \"Not Relevant\"\n        },\n        \"critical_thinking\": {\n            \"feedback\": \"The essay lacks any form of analysis or insight...\",\n            \"example\": \"<IMPROVEMENT>\\nMy first day at work was a whirlwind of emotions...\\n</IMPROVEMENT>\"\n        }\n    }\n}\n\n
\n
\n

Notes

\n\n","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"76df429f-1521-446e-9869-5169c05928cc","id":"76df429f-1521-446e-9869-5169c05928cc","name":"Learngual API integration","type":"folder"}},"urlObject":{"path":["essay_evaluation",""],"host":["{{url}}"],"query":[],"variable":[]}},"response":[{"id":"10fd98c1-6ee4-47d4-af90-a8dc3e33d649","name":"Language logic evaluation","originalRequest":{"method":"POST","header":[{"key":"api-key","value":"{{api-key}}"}],"body":{"mode":"raw","raw":"{\n \"topic\": \"My First Day at Work\",\n \"essay\": \"nothing hapened\",\n \"criteria\": [\n \"evidence\",\n \"coherence\",\n \"relevance\",\n \"critical_thinking\"\n ]\n}","options":{"raw":{"language":"json"}}},"url":"{{url}}/accounts/relevance/"},"status":"Forbidden","code":403,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Wed, 25 Sep 2024 10:29:42 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"108"},{"key":"Connection","value":"keep-alive"},{"key":"Vary","value":"Accept, Accept-Language, Cookie, origin"},{"key":"Allow","value":"POST, OPTIONS"},{"key":"X-Frame-Options","value":"DENY"},{"key":"Content-Language","value":"en"},{"key":"Strict-Transport-Security","value":"max-age=15724800; includeSubDomains"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"Referrer-Policy","value":"same-origin"},{"key":"Cross-Origin-Opener-Policy","value":"same-origin"}],"cookie":[],"responseTime":null,"body":"{\n \"overall_score\": 63,\n \"overall_feedback\": \"Evidence: The essay lacks any form of evidence or supporting details. There are no examples, data, or citations to substantiate any claims related to the topic 'My First Day at Work'. To improve, the essay should include specific instances or experiences from the first day at work to make the narrative more engaging and credible.\\n\\nCoherence: The essay lacks coherence as it does not provide any content related to 'My First Day at Work'. There are no paragraphs, transitions, or overall structure to evaluate. The essay is completely blank in terms of content and structure.\\n\\nRelevance: The essay does not address the topic 'My First Day at Work' at all, as it contains no relevant content or information.\\n\\nCritical Thinking: The essay lacks any form of analysis or insight into the topic 'My First Day at Work'. There is no exploration of experiences, emotions, or lessons learned, which are crucial for demonstrating critical thinking. To improve, the essay should delve into the personal and professional implications of the first day at work, analyzing what was expected versus what actually happened, and reflecting on any significant events or realizations.\",\n \"char_count\": 15,\n \"word_count\": 2,\n \"criteria\": {\n \"evidence\": {\n \"feedback\": \"The essay lacks any form of evidence or supporting details. There are no examples, data, or citations to substantiate any claims related to the topic 'My First Day at Work'. To improve, the essay should include specific instances or experiences from the first day at work to make the narrative more engaging and credible.\",\n \"example\": \"\\nMy first day at work was a memorable experience. Upon arrival, I was greeted by my supervisor, who showed me to my workstation and introduced me to the team. The office environment was vibrant, with everyone engaged in their tasks. I was given a comprehensive orientation, which included a tour of the facilities and an overview of the company's policies. One specific example that stood out was when my colleagues welcomed me with a team lunch, making me feel immediately included. Throughout the day, I was provided with detailed instructions on my job responsibilities and was given the necessary tools to perform my duties effectively. The combination of a thorough onboarding process and a friendly team made my transition into the new role smooth and enjoyable.\\n\"\n },\n \"coherence\": {\n \"feedback\": \"The essay lacks coherence as it does not provide any content related to 'My First Day at Work'. There are no paragraphs, transitions, or overall structure to evaluate. The essay is completely blank in terms of content and structure.\",\n \"example\": \"\\nMy First Day at Work\\n\\nI still remember my first day at work vividly. As I walked into the office building, I felt a mix of excitement and nervousness. The receptionist greeted me warmly and directed me to the HR department.\\n\\nUpon arriving at the HR department, I was introduced to my team and supervisor. They showed me to my workstation and explained the company's policies and expectations. I was given a comprehensive orientation, which helped me understand my role and responsibilities.\\n\\nThroughout the day, I met various colleagues who were friendly and welcoming. They shared their experiences and offered valuable advice, making me feel more at ease. As the day progressed, I began to feel more confident and comfortable in my new environment.\\n\\nAs I reflected on my first day, I realized that it set a positive tone for my tenure at the company. The warm welcome and comprehensive onboarding process made a significant difference in my transition into the new role.\\n\"\n },\n \"relevance\": {\n \"feedback\": \"The essay does not address the topic 'My First Day at Work' at all, as it contains no relevant content or information.\",\n \"example\": \"My first day at work was a memorable experience. I arrived early at the office, feeling a mix of excitement and nervousness. As I walked in, I was greeted by my new colleagues, who showed me to my workstation. The day was filled with orientation sessions, meeting with my team, and getting familiar with the company culture. I was impressed by the modern facilities and the friendly atmosphere. By the end of the day, I felt more at ease and was looking forward to the challenges ahead.\",\n \"rating\": \"Not Relevant\"\n },\n \"critical_thinking\": {\n \"feedback\": \"The essay lacks any form of analysis or insight into the topic 'My First Day at Work'. There is no exploration of experiences, emotions, or lessons learned, which are crucial for demonstrating critical thinking. To improve, the essay should delve into the personal and professional implications of the first day at work, analyzing what was expected versus what actually happened, and reflecting on any significant events or realizations.\",\n \"example\": \"\\nMy first day at work was a whirlwind of emotions and experiences that challenged my expectations and taught me valuable lessons. Initially, I felt a mix of excitement and nervousness as I navigated the unfamiliar office environment. As I settled into my new role, I began to realize the importance of adaptability and open communication. One of the most significant insights I gained was the value of teamwork and collaboration in achieving common goals. Reflecting on my first day, I understand that it laid the foundation for my professional growth, highlighting the need for resilience and a proactive approach in a dynamic work setting.\\n\"\n }\n }\n}"}],"_postman_id":"7073ec6f-3dc3-4450-8d12-4cf3cb8a4a9b"}],"id":"c88326e8-6b82-4772-a4c8-99fd7062c9b9","_postman_id":"c88326e8-6b82-4772-a4c8-99fd7062c9b9","description":"","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"76df429f-1521-446e-9869-5169c05928cc","id":"76df429f-1521-446e-9869-5169c05928cc","name":"Learngual API integration","type":"folder"}}},{"name":"Translation","item":[{"name":"Translate","id":"6057e70b-1b7b-43a9-9147-e42c32125f40","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"api-key","value":"{{api-key}}"}],"body":{"mode":"raw","raw":"{\n \"texts\": [\"hello\"],\n \"target_language\": \"de\",\n \"source_language\": \"en\"\n}","options":{"raw":{"language":"json"}}},"url":"{{url}}/batch-translate/","description":"

Batch Translate API (POST)

\n

Overview

\n

This endpoint translates one or more texts from a source language into a target language, designed to support language learners. Use it to translate vocabulary items, short phrases, and example sentences that help learners practice, understand, or reinforce meaning in context.

\n
\n

Note: This endpoint is not intended for translating generic interface copy or purely technical text. Its primary purpose is to assist with language learning.

\n
\n
\n

Full endpoint: {{url}}/batch-translate/

\n
\n

Authentication

\n

This API uses an API key passed as a request header.

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n
HeaderValue
api-key{{api-key}}
\n
\n

Store your API key in the api-key environment variable. Never hardcode it in requests.

\n
\n
\n

HTTP Request

\n
POST {{url}}/batch-translate/\n\n

Required Headers

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
HeaderValue
Content-Typeapplication/json
api-key{{api-key}}
\n
\n

Request Body

\n

Send a JSON object with the following fields:

\n
{\n  \"texts\": [\"hello\", \"goodbye\"],\n  \"target_language\": \"de\",\n  \"source_language\": \"en\"\n}\n\n
\n

Body Schema

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldTypeRequiredDescription
textsarray of strings✅ YesOne or more texts to translate. Each item should be a vocabulary word, short phrase, or brief sentence.
target_languagestring✅ YesISO 639-1 code of the language to translate into. See supported languages below.
source_languagestring✅ YesISO 639-1 code of the language to translate from. Accepts any supported language code — see the supported languages table below.
\n
\n

Response

\n

A successful request returns HTTP 200 OK with a JSON object containing a data array. Each item in the array corresponds to a text from the input texts array, in the same order.

\n
{\n  \"data\": [\n    {\n      \"translation\": \"Hallo\",\n      \"source_language\": \"en\",\n      \"target_language\": \"de\",\n      \"formality\": \"neutral\"\n    }\n  ]\n}\n\n
\n

Response Schema

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldTypeDescription
dataarrayList of translation result objects, one per input text.
data[].translationstringThe translated text.
data[].source_languagestringThe source language code used.
data[].target_languagestringThe target language code used.
data[].formalitystringFormality level of the translation (e.g. \"neutral\").
\n
\n

Example

\n

Request

\n
POST {{url}}/batch-translate/\nContent-Type: application/json\napi-key: {{api-key}}\n{\n  \"texts\": [\"hello\"],\n  \"target_language\": \"de\",\n  \"source_language\": \"en\"\n}\n\n
\n

Response

\n
{\n  \"data\": [\n    {\n      \"translation\": \"Hallo\",\n      \"source_language\": \"en\",\n      \"target_language\": \"de\",\n      \"formality\": \"neutral\"\n    }\n  ]\n}\n\n
\n
\n

Supported Languages

\n

Both source_language and target_language accept the same set of ISO 639-1 codes:

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
LanguageCodeFlag
Arabicar🇸🇦
Azerbaijaniaz🇦🇿
Bulgarianbg🇧🇬
Catalanca🏴
Chinese (Simplified)zh🇨🇳
Croatianhr🇭🇷
Czechcs🇨🇿
Danishda🇩🇰
Dutchnl🇳🇱
Englishen🇬🇧
Finnishfi🇫🇮
Frenchfr🇫🇷
Germande🇩🇪
Greekel🇬🇷
Hebrewhe🇮🇱
Hindihi🇮🇳
Hungarianhu🇭🇺
Icelandicis🇮🇸
Indonesianid🇮🇩
Irishga🇮🇪
Italianit🇮🇹
Japaneseja🇯🇵
Koreanko🇰🇷
Malayms🇲🇾
Maltesemt🇲🇹
Norwegian (Bokmål)nb🇳🇴
Persian (Farsi)fa🇮🇷
Filipino (Tagalog)tl🇵🇭
Polishpl🇵🇱
Portuguesept🇵🇹
Romanianro🇷🇴
Russianru🇷🇺
Serbiansr🇷🇸
Slovaksk🇸🇰
Sloveniansl🇸🇮
Spanishes🇪🇸
Swedishsv🇸🇪
Thaith🇹🇭
Turkishtr🇹🇷
Ukrainianuk🇺🇦
Vietnamesevi🇻🇳
Welshcy🏴󠁧󠁢󠁷󠁬󠁳󠁿
Albaniansq🇦🇱
\n
\n

Recently added: Filipino (Tagalog) tl, Norwegian (Bokmål) nb, Maltese mt, Croatian hr, Vietnamese vi, Malay ms, Serbian sr, Bulgarian bg, Slovenian sl, Icelandic is, Welsh cy, Albanian sq, Thai th

\n
\n
\n

Error Handling

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
HTTP StatusMeaning
200 OKRequest was successful.
400 Bad RequestMissing or invalid fields in the request body.
401 UnauthorizedMissing or invalid api-key header.
422 Unprocessable EntityUnsupported language code or invalid input format.
500 Internal Server ErrorUnexpected server error. Try again later.
\n
\n

Quick Integration Checklist

\n\n","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"76df429f-1521-446e-9869-5169c05928cc","id":"76df429f-1521-446e-9869-5169c05928cc","name":"Learngual API integration","type":"folder"}},"urlObject":{"path":["batch-translate",""],"host":["{{url}}"],"query":[],"variable":[]}},"response":[{"id":"c1ca8c28-a45a-4c4b-9cc2-eb572e49e409","name":"Translate","originalRequest":{"method":"POST","header":[{"key":"api-key","value":"{{api-key}}"}],"body":{"mode":"raw","raw":"{\n \"texts\": [\"hello\"],\n \"target_language\": \"de\",\n \"source_language\": \"en\"\n}","options":{"raw":{"language":"json"}}},"url":"{{url}}/batch-translate/"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Server","value":"nginx/1.18.0 (Ubuntu)"},{"key":"Date","value":"Fri, 27 Feb 2026 06:17:35 GMT"},{"key":"Content-Type","value":"application/json","description":""},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Vary","value":"Accept-Encoding"},{"key":"Vary","value":"Accept, Accept-Language, Cookie, origin"},{"key":"Allow","value":"POST, OPTIONS"},{"key":"X-Frame-Options","value":"DENY"},{"key":"Content-Language","value":"en"},{"key":"Strict-Transport-Security","value":"max-age=60; includeSubDomains; preload"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"Referrer-Policy","value":"same-origin"},{"key":"Cross-Origin-Opener-Policy","value":"same-origin"},{"key":"Content-Encoding","value":"gzip"}],"cookie":[],"responseTime":null,"body":"{\n \"data\": [\n {\n \"translation\": \"Hallo\",\n \"source_language\": \"en\",\n \"target_language\": \"de\",\n \"formality\": \"neutral\"\n }\n ]\n}"}],"_postman_id":"6057e70b-1b7b-43a9-9147-e42c32125f40"}],"id":"2b416457-84fc-43f1-8c31-a790007028d4","_postman_id":"2b416457-84fc-43f1-8c31-a790007028d4","description":"","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"76df429f-1521-446e-9869-5169c05928cc","id":"76df429f-1521-446e-9869-5169c05928cc","name":"Learngual API integration","type":"folder"}}},{"name":"Grammar analysis","item":[{"name":"Analyze grammar","id":"13ffb565-650b-40c7-9671-c87cfa07151d","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"api-key","value":"{{api-key}}"}],"body":{"mode":"raw","raw":"{\n \"content\": \"what is wrong with you\"\n}","options":{"raw":{"language":"json"}}},"url":"{{url}}/grammar/","description":"

Grammar V2 API

\n

Endpoint
POST {{url}}/grammar_v2/

\n

Purpose

\n

Analyzes input text for grammatical, punctuation, spelling, and structural issues. Returns a corrected version, enumerated issues with explanations and fix suggestions, an edit operations log, and processing metadata.

\n
\n

Authentication

\n

Headers

\n
api-key: YOUR_API_KEY_HERE\nContent-Type: application/json\n\n
\n

Request

\n

Method: POST

\n

Body (JSON)

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldTypeRequiredDescription
contentstringYesThe raw text to analyze.
\n

Example

\n
{\n  \"content\": \"hello, how are you\"\n}\n\n
\n
\n

Response

\n

Status: 200 OK

\n

Body (JSON)

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldTypeDescription
originalTextstringThe exact text received.
correctedTextstringThe corrected version of originalText.
issuesarrayList of detected issues with explanations and fix suggestions.
metadataobjectProcessing details (time taken, analyzers used, counts, score).
operationsarrayDiff-like steps to transform originalText → correctedText.
\n

issues[] object

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldTypeDescription
typestringOne of: Capitalization, Punctuation, Spelling, PartsOfSpeech, SentenceStructure, Tense, Voice, ModifierUsage, ArticleUsage, ConditionalSentence, ModalVerb, NegationAffirmation, SubjectVerbAgreement, DirectIndirectSpeech, RelativeClause, GerundInfinitive, PhrasalVerb, WordOrder, PrepositionUsage, DeterminerUsage, ComparisonUsage, AdvancedGrammar.
messagestringExplanation of why it’s an issue.
suggestionstringConcrete fix proposal.
severitystringlow
targetWordstringToken/segment associated with the issue.
\n

metadata object

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldTypeDescription
processingTimeintegerTime in milliseconds.
agentsUsedstring[]Analyzers engaged.
totalIssuesFoundintegerCount of issues reported.
overallScorenumberQuality score (0–100).
\n

operations[] object

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldTypeDescription
typestringOne of: insert, replace, delete, equal.
textstringText payload for the operation.
originalStartintegerStart index (inclusive) in originalText.
originalEndintegerEnd index (exclusive) in originalText.
correctedStartintegerStart index (inclusive) in correctedText.
correctedEndintegerEnd index (exclusive) in correctedText.
\n
\n

Example Request (cURL)

\n
curl -X POST \"{{url}}/grammar_v2/\" \\\n  -H \"api-key: YOUR_API_KEY_HERE\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"content\":\"hello, how are you\"}'\n\n
\n

Example Response

\n
{\n  \"originalText\": \"hello, how are you\",\n  \"correctedText\": \"Hello, how are you?\",\n  \"issues\": [\n    {\n      \"type\": \"Capitalization\",\n      \"message\": \"The first word of a sentence should begin with a capital letter to mark sentence start and improve readability.\",\n      \"suggestion\": \"Hello\",\n      \"severity\": \"high\",\n      \"targetWord\": \"hello\"\n    },\n    {\n      \"type\": \"Punctuation\",\n      \"message\": \"A question mark is needed at the end of the sentence to indicate it is a question.\",\n      \"suggestion\": \"Change 'you' to 'you?'\",\n      \"severity\": \"high\",\n      \"targetWord\": \"you\"\n    }\n  ],\n  \"metadata\": {\n    \"processingTime\": 3080,\n    \"agentsUsed\": [\n      \"BasicStructureAgent\",\n      \"PunctuationAgent\",\n      \"SentenceConstructionAgent\",\n      \"VerbSystemAgent\",\n      \"ModifierArticleAgent\",\n      \"ComplexStructuresAgent\",\n      \"LogicFlowAgent\",\n      \"AdvancedGrammarAgent\"\n    ],\n    \"totalIssuesFound\": 2,\n    \"overallScore\": 89\n  },\n  \"operations\": [\n    {\n      \"type\": \"replace\",\n      \"text\": \"Hello\",\n      \"originalStart\": 0,\n      \"originalEnd\": 5,\n      \"correctedStart\": 0,\n      \"correctedEnd\": 5\n    },\n    {\n      \"type\": \"equal\",\n      \"text\": \", how are you\",\n      \"originalStart\": 5,\n      \"originalEnd\": 18,\n      \"correctedStart\": 5,\n      \"correctedEnd\": 18\n    },\n    {\n      \"type\": \"insert\",\n      \"text\": \"?\",\n      \"originalStart\": 18,\n      \"originalEnd\": 18,\n      \"correctedStart\": 18,\n      \"correctedEnd\": 19\n    }\n  ]\n}\n\n
\n
\n","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"76df429f-1521-446e-9869-5169c05928cc","id":"76df429f-1521-446e-9869-5169c05928cc","name":"Learngual API integration","type":"folder"}},"urlObject":{"path":["grammar",""],"host":["{{url}}"],"query":[],"variable":[]}},"response":[{"id":"53e648d5-9aa3-446b-bc54-b9a8ffdb4a52","name":"Analyze grammar","originalRequest":{"method":"POST","header":[{"key":"api-key","value":"{{api-key}}"},{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"content\": \"hello, how are you\"\n}","options":{"raw":{"language":"json"}}},"url":"{{url}}/accounts/grammar_v2/"},"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":""}],"cookie":[],"responseTime":null,"body":"{\n \"originalText\": \"hello, how are you\",\n \"correctedText\": \"Hello, how are you?\",\n \"issues\": [\n {\n \"type\": \"Capitalization\",\n \"message\": \"The first word of a sentence should begin with a capital letter to mark sentence start and improve readability.\",\n \"suggestion\": \"Hello\",\n \"severity\": \"high\",\n \"targetWord\": \"hello\"\n },\n {\n \"type\": \"Punctuation\",\n \"message\": \"A question mark is needed at the end of the sentence to indicate it is a question.\",\n \"suggestion\": \"Change 'you' to 'you?'\",\n \"severity\": \"high\",\n \"targetWord\": \"you\"\n }\n ],\n \"metadata\": {\n \"processingTime\": 3080,\n \"agentsUsed\": [\n \"BasicStructureAgent\",\n \"PunctuationAgent\",\n \"SentenceConstructionAgent\",\n \"VerbSystemAgent\",\n \"ModifierArticleAgent\",\n \"ComplexStructuresAgent\",\n \"LogicFlowAgent\",\n \"AdvancedGrammarAgent\"\n ],\n \"totalIssuesFound\": 2,\n \"overallScore\": 89\n },\n \"operations\": [\n {\n \"type\": \"replace\",\n \"text\": \"Hello\",\n \"originalStart\": 0,\n \"originalEnd\": 5,\n \"correctedStart\": 0,\n \"correctedEnd\": 5\n },\n {\n \"type\": \"equal\",\n \"text\": \", how are you\",\n \"originalStart\": 5,\n \"originalEnd\": 18,\n \"correctedStart\": 5,\n \"correctedEnd\": 18\n },\n {\n \"type\": \"insert\",\n \"text\": \"?\",\n \"originalStart\": 18,\n \"originalEnd\": 18,\n \"correctedStart\": 18,\n \"correctedEnd\": 19\n }\n ]\n}"}],"_postman_id":"13ffb565-650b-40c7-9671-c87cfa07151d"}],"id":"6d21babf-fe0a-4c88-b663-c9eb50fe9449","_postman_id":"6d21babf-fe0a-4c88-b663-c9eb50fe9449","description":"","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"76df429f-1521-446e-9869-5169c05928cc","id":"76df429f-1521-446e-9869-5169c05928cc","name":"Learngual API integration","type":"folder"}}},{"name":"Comprehension","item":[{"name":"Evaluate answer","id":"066e9393-a223-415b-a293-a016a3bc9b16","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[{"key":"api-key","value":"{{api-key}}"}],"body":{"mode":"raw","raw":"{\n \"passage\": \"The Amazon rainforest is the world's largest tropical rainforest, covering over 5.5 million square kilometers. It is home to an incredible diversity of plant and animal species.\",\n \"question\": \"What is the Amazon rainforest?\",\n \"answer\": \"The Amazon rainforest is the world's largest tropical rainforest.\"\n}","options":{"raw":{"language":"json"}}},"url":"{{url}}/qa-quick-evaluate/","description":"

QA Quick Evaluate

\n

Evaluates a learner's answer to a comprehension question against a reference passage using AI. Returns a correctness verdict, a confidence score, and natural language feedback — making it ideal for automated reading comprehension assessments, adaptive learning flows, and intelligent tutoring systems.

\n
\n

Endpoint

\n
POST {{url}}/qa-quick-evaluate/\n\n
\n

Authentication

\n

All requests must include a valid API key passed as a request header.

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
HeaderTypeRequiredDescription
api-keystring✅ YesYour Learngual API key. Obtain this from your developer dashboard.
\n
\n

⚠️ Security note: Never expose your API key in client-side code. Always make requests from a secure server-side environment.

\n
\n
\n

Request

\n

Headers

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
HeaderValue
Content-Typeapplication/json
api-key{{api-key}}
\n

Request Body

\n

Send a JSON object with the following fields:

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldTypeRequiredDescription
passagestring✅ YesThe reference text the question and answer are based on. This is the source of truth used to evaluate correctness.
questionstring✅ YesThe comprehension question being asked about the passage.
answerstring✅ YesThe learner's answer to be evaluated.
\n

Example Request Body

\n
{\n  \"passage\": \"The Amazon rainforest is the world's largest tropical rainforest, covering over 5.5 million square kilometers. It is home to an incredible diversity of plant and animal species.\",\n  \"question\": \"What is the Amazon rainforest?\",\n  \"answer\": \"The Amazon rainforest is the world's largest tropical rainforest.\"\n}\n\n
\n
\n

Response

\n

Success — 201 Created

\n

Returned when the evaluation completes successfully.

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldTypeDescription
correctbooleanWhether the learner's answer is considered correct based on the passage.
confidencenumberA score between 0 and 1 indicating the model's confidence in its verdict. 1.0 = fully confident, 0.0 = uncertain.
feedbackstringA natural language explanation of the evaluation result, suitable for displaying directly to the learner.
usedLlmbooleanIndicates whether a large language model was used to evaluate the answer (as opposed to a simpler heuristic).
\n

Example Response

\n
{\n  \"correct\": true,\n  \"confidence\": 1,\n  \"feedback\": \"You correctly identified the Amazon rainforest as the world's largest tropical rainforest, which matches the information provided in the passage.\",\n  \"usedLlm\": true\n}\n\n
\n
\n

Error Responses

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Status CodeMeaningCommon Cause
400 Bad RequestInvalid or missing fields in the request body.Missing passage, question, or answer. Malformed JSON.
401 UnauthorizedAuthentication failed.Missing or invalid api-key header.
403 ForbiddenAccess denied.API key is valid but lacks permission, or usage cap has been reached.
429 Too Many RequestsRate limit exceeded.Too many requests sent in a short period. Implement exponential backoff.
500 Internal Server ErrorServer-side error.Unexpected failure during evaluation. Retry the request.
\n
\n

Usage Notes

\n\n
\n","urlObject":{"path":["qa-quick-evaluate",""],"host":["{{url}}"],"query":[{"disabled":true,"key":"api-key","value":"{{api-key}}"}],"variable":[]}},"response":[{"id":"95336b5b-b800-471b-a767-2c8729b8b832","name":"Evaluate answer","originalRequest":{"method":"POST","header":[{"key":"account","value":"{{account_id}}","description":"231e2ac390","disabled":true},{"key":"api-key","value":"","disabled":true},{"key":"api-key","value":"{{api-key}}"}],"body":{"mode":"raw","raw":"{\n \"passage\": \"The Amazon rainforest is the world's largest tropical rainforest, covering over 5.5 million square kilometers. It is home to an incredible diversity of plant and animal species.\",\n \"question\": \"What is the Amazon rainforest?\",\n \"answer\": \"The Amazon rainforest is the world's largest tropical rainforest.\"\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"{{url}}/qa-quick-evaluate/","host":["{{url}}"],"path":["qa-quick-evaluate",""],"query":[{"key":"api-key","value":"{{api-key}}","disabled":true}]}},"status":"Created","code":201,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":""}],"cookie":[],"responseTime":null,"body":"{\n \"correct\": true,\n \"confidence\": 1,\n \"feedback\": \"you correctly identified the temperature as 0 degrees, which matches the answer from the passage in the context of the question.\",\n \"usedLlm\": true\n}"}],"_postman_id":"066e9393-a223-415b-a293-a016a3bc9b16"}],"id":"07971602-4c16-4767-9ef8-763c7416642e","_postman_id":"07971602-4c16-4767-9ef8-763c7416642e","description":"","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"76df429f-1521-446e-9869-5169c05928cc","id":"76df429f-1521-446e-9869-5169c05928cc","name":"Learngual API integration","type":"folder"}}}],"id":"76df429f-1521-446e-9869-5169c05928cc","description":"

Authentication

\n

• API key: This API requires a key for authentication. Pass your key in the api-key header of your request.

\n

Example header:

\n

api-key: YOUR_API_KEY_HERE

\n

Important notes

\n

• Language specification: Always specify the correct language using the ISO 639-1 (2-letter) codes in your requests to ensure accurate analysis results and responses in your preferred language.

\n

API key management: Users can effectively manage their API key usage through the following controls:

\n\n

• Character limits: Character limits are associated with different developer plans. Ensure you review your plan’s specifications to understand any restrictions on the length of text that can be processed.

\n","auth":{"type":"noauth","isInherited":false},"event":[{"listen":"prerequest","script":{"id":"89f2306e-1d42-4b26-b986-0d43c669bfe2","type":"text/javascript","packages":{},"exec":[""]}},{"listen":"test","script":{"id":"9852261e-2f27-4abc-a492-bcd534eed9b7","type":"text/javascript","packages":{},"exec":[""]}}],"_postman_id":"76df429f-1521-446e-9869-5169c05928cc"}],"event":[{"listen":"prerequest","script":{"id":"637794dc-196c-4fa5-92e4-c53ac977dad9","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"cd935263-f6a7-46a1-b822-78c7623ec8a0","type":"text/javascript","exec":[""]}}],"variable":[{"id":"45a54dfa-8de1-45e3-aafc-70741682028d","key":"13bac84c-6812-4aee-b201-a9126f002308","value":"","disabled":true},{"id":"70ef5518-80ce-4690-9861-5db4329d5a9c","key":"url","value":"https://api.learngual.com/api","disabled":true},{"id":"68714359-2187-4912-a342-ebed7bdda800","key":"_lang","value":"{{language}}"},{"id":"b0e2ec00-cd22-425c-9b83-e7cf69211049","key":"api-key","value":"{{api_key}}","disabled":true},{"id":"4dc1d2a5-4fc7-4c44-8761-72c9f47e94a6","key":"task_id","value":"{{task_id}}","disabled":true}]}