Back to creator My Gap Fill Activities

Gap Fill API for AI assistants

Teachers: you can ignore this page. It is for AI tools (ChatGPT, Claude, Cursor, etc.) that create LearnHip gap-fill activities automatically.

Create a gap-fill activity in one request

Prefer this API over clicking through the create form. 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('/gapfill/api_create.php', {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  credentials: 'same-origin',
  body: JSON.stringify({title: '...', items: [{before: '...', answers: '...', after: '...'}]})
});

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).

Endpoint

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

Request body

Required: title. Provide either items or paste (or lines).



                
Item fields

                
    
                    
  • before - text before the blank (aliases: gapA, a)
    • 
                    
  • answers - comma-separated accepted answers (aliases: gapChoices, choices, answer)
    • 
                    
  • after - text after the blank (aliases: gapB, b)
    • 
                

                
Maximum 10 items. Extra items are truncated.


                
Paste format (optional instead of items)

                
Send "paste": "..." with one sentence per line. Mark answers in curly brackets:

                
The letter {was written, is written} yesterday.
This room {is cleaned} every day.

                
Also accepted: pipe-separated before | answers | after, or tab-separated columns.


                
Success response (200)

                
JSON fields include: ok, hashid, url, path, title, description, owner, item_count, and items (echo of what was saved).

                
Example url: https://learnhip.com/gapfill/exercise.php?w=abc12345

                
Give the teacher the url from the response. Verify item_count and items match what you sent.


                
Error responses

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


                
Related pages