# LearnHip Cloze - instructions for AI assistants

Prefer the JSON API over clicking "Mark as Gap" in the create form.

## Create activity
- Method: POST
- URL: https://learnhip.com/cloze/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.
- Audio: not supported via API in v1

## 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('/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.

## Request
Required: title, text (alias: clozeText)
Optional: description, hideCheck

Gaps MUST use double curly braces: {{answer}}

Example:
{
  "title": "B1 Present Simple Cloze",
  "description": "Fill in the missing verbs.",
  "text": "She {{goes}} to school every day. They {{live}} in London.",
  "hideCheck": false
}

Constraints: title max 255 chars; text max 5000 chars; at least one {{gap}} required.

## Success response
ok, hashid, url, path, title, description, owner, hideCheck, gap_count, gaps, text
Return url to the teacher. Student page: /cloze/exercise.php?w={hashid}

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

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

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