# LearnHip - instructions for AI assistants

Prefer JSON APIs over clicking through create forms when building activities for teachers.

Site: https://learnhip.com

## Activity create APIs

### Cloze (fill gaps in a paragraph)
- Create: POST https://learnhip.com/cloze/api_create.php
- Docs: https://learnhip.com/cloze/api-docs.php
- Details: https://learnhip.com/cloze/llms.txt
- Gap format: {{answer}} inside the text
- Human UI: https://learnhip.com/cloze/create.php

### Gap fill (sentence rows with blanks)
- Create: POST https://learnhip.com/gapfill/api_create.php
- Docs: https://learnhip.com/gapfill/api-docs.php
- Details: https://learnhip.com/gapfill/llms.txt
- Human UI: https://learnhip.com/gapfill/create.php

## Auth
Logged-in LearnHip session required (no guests on the API).
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: '...'}]})
});

(For cloze, use /cloze/api_create.php and body {title: '...', text: '...'}.)

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

## Rate limits
- 10 API creates per account per hour
- 20 API creates per IP per hour
Over limit returns HTTP 429 with error rate_limited and retry_after (seconds).

## Rule of thumb
If a teacher asks you to make a LearnHip activity, read the matching llms.txt / api-docs above and create via API in one request. Return the share URL from the JSON response.