# LearnHip Gap Fill (gapfill) - instructions for AI assistants

Prefer the JSON API over clicking the create form.

## Create activity
- Method: POST
- URL: https://learnhip.com/gapfill/api_create.php
- Content-Type: application/json
- Rate limits: 10 creates/account/hour and 20 creates/IP/hour. Over limit: HTTP 429 error rate_limited.

## Auth
Logged-in LearnHip session required (no guests). Use the teacher's existing session cookie when acting in their browser.

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.

## Request
Required: title
Provide items[] OR paste (or lines)

Example:
{
  "title": "Passive Voice Practice",
  "description": "Fill in the gaps with the correct passive form.",
  "items": [
    { "before": "The letter ", "answers": "was written, is written", "after": " yesterday." },
    { "before": "This room ", "answers": "is cleaned", "after": " every day." }
  ]
}

Item fields: before, answers, after (aliases: gapA/gapChoices/gapB, a/choices/b, answer)
Max 10 items.

Paste alternative (one sentence per line):
"paste": "The letter {was written, is written} yesterday.\nThis room {is cleaned} every day."

## Success response
ok, hashid, url, path, title, description, owner, item_count, items
Return url to the teacher. Student page: /gapfill/exercise.php?w={hashid}

## Human UI
https://learnhip.com/gapfill/create.php

## Site index
https://learnhip.com/llms.txt

## Full docs
https://learnhip.com/gapfill/api-docs.php