Back to creator My Cloze Activities

Cloze API for AI assistants

Teachers: you can ignore this page. It is for AI tools that create LearnHip cloze activities automatically. Prefer the API over clicking “Mark as Gap” in the browser.

Create a cloze activity in one request

Authenticate with the user’s existing LearnHip session cookie when browsing as that user. Login is required — guests cannot use this API (the human create form still allows guest creation with expiry).

Auth note: This is a same-origin request. Call it via fetch() from the page's own JavaScript context with credentials: 'same-origin' (or 'include') - the browser sends the existing session cookie automatically, the same way this site's own frontend calls its APIs. No need to read or set cookies manually. 

fetch('/cloze/api_create.php', {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  credentials: 'same-origin',
  body: JSON.stringify({title: '...', text: '...'})
});

Use credentials: 'same-origin' rather than setting headers manually.

Rate limits: 10 creates per account per hour, and 20 per IP per hour. Over limit returns HTTP 429 (rate_limited). Audio upload is not supported via this API (v1).

Endpoint

POST https://learnhip.com/cloze/api_create.php
Content-Type: application/json

Request body

Required: title and text (alias: clozeText). Mark each gap with double curly braces.



                
Gap format

                
    
                    
  • Use {{answer}} around each word or phrase students must type.
    • 
                    
  • Example: The cat {{sat}} on the {{mat}}.
    • 
                    
  • At least one gap is required. Max text length: 5,000 characters. Max title: 255 characters.
    • 
                


                
Optional fields

                
    
                    
  • description — instructions for students
    • 
                    
  • hideCheck — true to remove the Check button (in-class correction)
    • 
                


                
Success response (200)

                
JSON includes: ok, hashid, url, path, title, description, owner, hideCheck, gap_count, gaps, text.

                
Example student URL: https://learnhip.com/cloze/exercise.php?w=abc12345

                
Give the teacher the url. Verify gap_count and gaps match what you intended.


                
Error responses

                
JSON with ok: false, plus error and message. Common errors: login_required (401), rate_limited (429), empty_title, empty_text, no_gaps, title_too_long, text_too_long, invalid_json, method_not_allowed.


                
Related pages